Architecture and technical information

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

Authentication

NOBB Export API uses basic authentication. Access to the various endpoints depends on the kind of subscription your user has.

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. In the Swagger section of the documentation, you will find both a Swagger file for the latest version of all endpoints and a Swagger file for all supported endpoints/versions.

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.

Response format

All responses are JSON formatted. In earlier versions of the API, an XML format was supported, so you may see traces of this here and there. For more information on legacy XML formats, see below.

Legacy formats

Earlier versions of the API supported XML as a response format. These formats are now deprecated and will not be further developed. Please see the page Migration to version 1 for information on migration to JSON formats.

Information about the XML formats can be downloaded here.

The XSD schemas are available here: