Architecture and technical information

NOBB Connect Supplier is a REST/JSON based API, built using standard and well-known building blocks for a modern API.

Asynchronous messages

All create/update (POST/PATCH) endpoints are asynchronous endpoints. This means that the response for these methods will be an HTTP 202 (Accepted) response, together with a link to a status endpoint where the progress of the create/update process can be followed.

Expandable JSON schema

The API will not support a strict JSON schema, as the different data models will expand in the future. it is therefore strongly recommended for clients of the API to use the Tolerant Reader design pattern (see http://servicedesignpatterns.com/WebServiceEvolution/TolerantReader). The API may change in a backwards-compatible way without prior notice (e.g. new optional parameters may be added to the request,  new fields may be added to the response). The order of the fields in a returned JSON is not significant and may change.

Versioning

The API is versioned, and any breaking changes will be released in a new version. We are versioning individual resources, not the whole API. End-of-life of old versions will be announced at least 6 months ahead of time.

Partial updates

The API will not support PUT for full updates of entities. Instead, all endpoints will support PATCH for partial updates of individual attributes for an entity. With this in mind, it is important in a PATCH call to distinguish between omitting an attribute (which will leave the attribute unchanged) and setting the attribute to NULL (which will remove the attribute value).

HTTP Codes

The API uses the following HTTP Codes:

Rate limits

In order to ensure the quality of our services, our APIs may be subject to rate limiting. Rate limits may be set globally on a client level or on specific endpoints. Byggtjeneste reserves the right to modify the rate limits at any time.  For up-to-date information on rate limits, you can review the HTTP response headers returned from rate-limited endpoints.

API requests to selected endpoints will return HTTP response headers that provide relevant data on the current status of your rate limits for that endpoint. If you receive a rate limit-related response header, it will include numeric information detailing your status.

• x-ratelimit-limit: The maximum number of requests available in the current time frame.

• x-ratelimit-remaining: The number of remaining requests in the current time frame.

• x-ratelimit-reset: A UNIX timestamp of the expected time when the rate limit will reset.

Handle rates limitations in code

You should add logic to handle cases in which you exceed the provided rate limits and receive HTTP Status Code 429 (Too Many Requests). If a retry is needed, you should wait until the reset time.

Error handling

The API will generally use HTTP Codes to handle errors. There may also be a short text in the response body indicating more details about the error.

For validation and serialization errors, the API will return JSON content with more detailed information. This will have the following structure:

{
    "errors": {
        "fieldName": [
            "Error description"
        ]
    },
    "title": "One or more validation error.",
    "status": 400,
    "detail": "There were issues validating constraints of properties of the supplied request body."
}

Server URLs