API Best Practices

Our API let's you interact with your queues, listeners, and messages. This page will give you an overview of our API while API Reference will give you a detailed impression of the available endpoints and schemas.

The API is exposed as an HTTP/1 and HTTP/2 service over TLS. All endpoints live under the URL https://api.discue.io.

Tolerant Reading

We recommend all clients to implement the Tolerant Reader pattern as described by Martin Fowler. The advantage of this pattern is that it allows us to incrementally improve the API while your implementation is only coupled as minimal as possible.

The JavaScript function JSON.parse allows such an implementation of the tolerant reader pattern. The function will merely create a nested hash from the JSON string without application only validation. The same applies to the Response.json method as you can see below.

const body = {
  "name": "myapp.io/deletion-request-queue"
}

const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'X-API-KEY':'API_KEY'
}

const response = await fetch('http://api.example.com/v1/queues', {
  method: 'PUT',  body,  headers
})

// Response.json does not care about missing fields, because it does not know about them
const body = await response.json()

If you are using Java with Bean Validation and have annotated your domain classes with validation constraints, than you are not following the tolerant reader pattern. In the example below, the implementation would expect our internal ids to have a certain format. The expectation would fail and your application would break, after we had changed the format of our internal ids.

public class Queue {
    
    @Pattern("[0-9]{32}")
    @NotBlank(message = "Id is required")
    private String id;
    
    @NotBlank(message = "Name is required")
    private String name;  
}

✔ Read only data you need, ignore everything else.

Follow Hypermedia Links

ℹ️ Hypermedia links are only present if the response status code equals 200.

Hypermedia controls are the final level of the REST API maturity model. These controls - in the form of HTTP URLS - allow a REST service to present URLs to the client that are in the relation to the current resource.

All success messages of our REST API endpoints, return hypermedia links. For example, whenever you create or get a queue, the response will contain the URL to the new resource and URLs to all subresources like listeners and messages.

Below you can see the default response of the GET method of the queue endpoint.

{
  "queue": {
    "id": "180994c-b6b2-4d0e-b7ad-414716e83386",
    "name": "myapp.io/delete-user-queue",
    "listeners": [
      {
        "id": "36a650fc-9594-47d3-9c36-26b89b464858",
        "name": "myapp.io/delete-user-listener-64fae19"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.example.com/queues/180994c-b6b2-4d0e-b7ad-414716e83386"
    },
    "myapp.io/delete-user-listener-64fae19": {
      "href": "https://api.example.com/queues/180994c-b6b2-4d0e-b7ad-414716e83386/listeners/0644659f-b47b-4668-86dd-a496cb7fbc76"
    }
  }
}

The schema for the hypermedia responses and links is as described below.

{
    "_links": {
        "self": {
            "href": "<< URL to current resource >>"
        },
        "<< name of subresource 1 >>": {
            "href": "<< URL to subresource 1 >>"
        },
        "<< name of subresource n >>": {
            "href": "<< URL to subresource n >>"
        }
    }
}

Depending on the number of subresources, there will be an equivalent number of additional links. The self link will aways be present.

✔ Use hypermedia links of our success responses instead of hardcoded URL to access our API. That way you will always use the latest backwards compatible endpoint.

Use Timeouts

Use Pagination

ℹ️ Pagination is not yet available.

Requests that return multiple items will be paginated to 10 items by default. You can specify further pages with the ?page parameter. For some resources, you can also set a custom page size up to 100 with the ?per_page parameter. Note that for technical reasons not all endpoints respect the ?per_page parameter.

curl 'https://api.discue.io/users?page=2&per_page=100'

Rate Limiting

ℹ️ Rate limiting is not yet available.

We limit the number of calls you can make over a certain period of time. Rate limits vary and are specified by the following header in all responses:

Header Name	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per minute.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The time at which the current rate limit window resets in UTC epoch seconds.

If you exceed the rate limit, an error response returns with the status 429 Too Many Requests.

Status: 429 Too Many Requests