Architecture and technical information

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

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 change 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.

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.

Server URLs