• REST API
• Feedback API
• Print API
• OAuth2 API
• How to use the API
  • Valid API request
  • API request to expose HTTP response headers
  • API request that includes the exit code
• Authentication
  • OAuth2 tokens
  • Session cookie
• Status codes
• Pagination
  • Offset-based pagination
    • Pagination links
• Path parameters
• Request Payload
• Data validation and error reporting
• Unknown route
• Content type
  • JSON Merge Patch

API Reference

REST API

The ezeep Blue REST API allows to manage almost all objects (e.g. organizations, users, printers, connectors, rules, print jobs) in the ezeep Blue world.

For a list of the available resources and their endpoints, see ezeep Blue REST API resources.

You can also use a partial OpenAPI definition, to test the API directly from the ezeep Blue user interface.

Feedback API

ezeep Blue provides a web API to collect the Feedback from the mobile clients, so that we can easily evaluate working and non-working printers or drivers.

Print API

ezeep Blue provides a web API that allows to print documents on ezeep Blue printers that are assigned to an user as well as get the rendered data stream back to be forwarded to an local print device connected to the local network (Direct WiFi print).

OAuth2 API

ezeep Blue provides an OAuth2 compatible authentication endpoint

How to use the API

API requests must include the API version in path. Currently only API version v1 is available.

Valid API request

If you consider api2.ezeep.com endpoint:

curl "https://api2.ezeep.com/printing/v1/printers/" --header "Authorization: Bearer $access_token"

or shell curl "https://api2.ezeep.com/printing/v1/printers/" --header "Cookie: ezp_session_id=$session_cookie"

The API uses JSON to serialize data. You don’t need to specify .json at the end of the API URL.

API request to expose HTTP response headers

If you want to expose HTTP response headers using curl as API request tool, use the --include option:

curl --include "https://api2.ezeep.com/printing/v1/printers/" --header "Authorization:Bearer $access_token"
HTTP/1.1 200 OK
...

This request can help you investigate an unexpected response.

API request that includes the exit code

If you want to expose the HTTP exit code, include the --fail option:

curl --fail "https://api2.ezeep.com/printing/v1/does-not-exist/" --header "Authorization:Bearer $access_token"
curl: (22) The requested URL returned error: 404 Not Found

The HTTP exit code can help you diagnose the success or failure of your REST request.

Authentication

Almost all API requests require authentication. When authentication is not required, the documentation for each endpoint specifies this.

There are two ways you can authenticate with the ezeep Blue API:

• OAuth2 tokens
• Session cookie

If authentication information is not valid or is missing, ezeep Blue returns an error message with a status code of 401:

{
  "detail":"Invalid authentication. Could not decode token."
}

or json { "detail":"Authentication credentials were not provided." }

OAuth2 tokens

You can use an OAuth2 token to authenticate with the API by passing it in the Authorization header.

Example of using the OAuth2 token in a header:

curl --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/"

Read more about ezeep Blue OAuth2 authentication.

NOTE: ezeep Blue OAuth access tokens have an expiration time of one hour. You can use the refresh_token parameter to refresh tokens. Integrations may need to be updated to use refresh tokens prior to expiration, which is based on the expires_in property in the token endpoint response. See OAuth2 token documentation for examples requesting a new access token using a refresh token.

Session cookie

Signing in to the main ezeep Blue Portal application sets a ezp_session_id cookie. The API uses this cookie for authentication if it’s present. A session cookie will be returned by the ezeep Authentication Service after opening the URL https://account.ezeep.com/auth/signin/ in a browser and successfully presenting a user’s credentials. The cookie is scoped to *.ezeep.com and not readable by scripts. Retrieval of a session Cookie via API is not supported. Information about the current logged in user a script can get by reading the answer of the URL https://account.ezeep.com/auth/me/ using the GET operation.

NOTE: The primary user of this authentication method is the web frontend of the ezeep Blue Portal itself.

Status codes

The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.

The following table gives an overview of how the API functions generally behave.

The following table shows the possible return codes for API requests.

Pagination

The ezeep Blue API supports the following pagination methods:

• Offset-based pagination. This is the default method and is available on all endpoints.
• Keyset-based pagination. Added to selected endpoints but being progressively rolled out.

For large collections, for performance reasons we recommend keyset pagination (when available) instead of offset pagination.

Offset-based pagination

Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:

In the following example, we list 50 namespaces per page:

curl --request GET --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/?limit=50"

Pagination links

Pagination links are returned as part of the content in each paged response. prev and next contain the relevant links. Be sure to use these links instead of generating your own URLs. Additionally count is set to the number of total results.

In the following cURL example, we limit the output to three items per page (limit=3) and we request an offset of 3 (offset=3) of comments printers:

curl --head --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=3"

The response payload is: json { "count": 10, "next": "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=6", "previous": "https://api2.ezeep.com/printing/v1/printers/?limit=3&offset=0", "results": [ {"id": "1f3dac2b-da63-48eb-8b22-fcaa4c76a439", ...} ... ] }

Path parameters

If an endpoint has path parameters, the documentation displays them with a preceding colon.

For example:

DELETE /printers/:id/

The :id path parameter needs to be replaced with the printer ID. The colons : shouldn’t be included.

The resulting cURL request for a project with ID a3845dfd-fd2d-4918-913e-ec6c1f70aafe is then:

curl --request DELETE --header "Authorization: Bearer <access_token>" "https://api2.ezeep.com/printing/v1/printers/a3845dfd-fd2d-4918-913e-ec6c1f70aafe/"

Path parameters that are required to be URL-encoded must be followed. If not, it doesn’t match an API endpoint and responds with a 404.

Request Payload

API Requests can use parameters sent as query strings or as a payload body. GET requests usually send a query string, while PUT or POST requests usually send the payload body:

• Query string:

  curl --request GET "https://api2.ezeep.com/printing/v1/printers/?name=<example-name>&location=<example-location>"
  

• Request payload (JSON):

  curl --request POST --header "Content-Type: application/json" \
       --data '{"name":"<example-name>", "location":"<example-location>"}' "https://api2.ezeep.com/printing/v1/printers/"
  

URL encoded query strings have a length limitation. Requests that are too large result in a 414 Request-URI Too Large error message.

Data validation and error reporting

When working with the API you may encounter validation errors, in which case the API returns an HTTP 400 error.

Such errors appear in the following cases:

• A required attribute of the API request is missing (for example, the title of an issue isn’t given).
• An attribute did not pass the validation (for example, the user bio is too long).

When an attribute is missing, you receive something like:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "detail":"Authentication credentials were not provided"
}

When a validation error occurs, error messages are different. They hold all details of validation errors:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "errors": [
        {
            "field": "location"
            "message": "Ensure this field has no more than 255 characters"
        }
    ]
}

This makes error messages more machine-readable. The format can be described as follows:

{
    "errors": [
        {
            "field": "<field-name>",
            "message": "<error-message>"
        },
        ...
    ]
}

Unknown route

When you attempt to access an API URL that doesn’t exist, you receive a 404 Not Found message.

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "detail": "Not Found"
}

Content type

The ezeep Blue API supports the application/json content type by default.

JSON Merge Patch

Selected PATCH APIs accept application/merge-patch+json content type according to RFC 7396 with required request header:

Content-Type: application/merge-patch+json

• All attributes are optional, including those required when adding a new resource.
• Requests should only include attributes intended to be modified. Omitted attributes will be left as is.
• Explicitly sending null will reset an attribute to its default value.
• Attempts to reset an attribute that is required when adding the resource will be rejected with 400 Bad Request.