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:

Pagination

Pagination is a feature introduced with v2 endpoints that return more results than can be returned in a single response. Pagination is required in cases where there are more matching results than the max pageSize defined for a resource. Some endpoints on previous versions could return a lot of data in response to a single request, which can be problematic to handle for clients. With pagination large results will be split into multiple, more manageable pages.

Currently the following endpoints support paging:

• GET api/v2/items

• POST api/v2/items

These endpoints will accept the following parameters:

pageSize: the max number of items returned in a single response. If no value is set for this parameter, the default value of 1000 will be used. Max allowed pageSize is 10000.

pageToken: set to the value of “forwardToken” from the previous request’s response, to get the next page of the results. Set the value of “backwardToken” for the previous page of results. This parameter will not have any value for the initial request.

sortField: name of the field the response should be sorted by. For most scenarios this could be left out, to fall back to the default value. (eg. NOBB number for api/v2/items endpoints). For the item endpoints, supported fields are currently NobbNo, OwnerParticipantNo and Created.

sortOrder: the order to sort the response by. Can be set to “asc” for ascending order, or “desc” for descending order. The default value is “asc”.

Response from endpoints that supports paging will include the following values, as HTTP headers:

x-totalHits: the total number of items in the result.

x-forwardToken: an opaque string that should be passed as the pageToken parameter to get the next page of the results. If this response header is not present, you have all the results, and no more pages are available.

x-backwardToken: an opaque string that should be passed as the pageToken parameter to get the previous page of the results.

Note that the tokens have a lifetime of 2 hours. If the token has expired it will not be considered, which means the response will be returned from the first page again.

Pagination example

In the example below we are making a request to an endpoint, where the result consists of three pages, since we have defined a pageSize of 100 and the the x-total-hits is 300. The response will be ordered by NOBB number, ascending, which is the default for the resource in this example.

Initial request

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100

Response headers

x-total-hits: 300

x-forward-token: RnwyfDUzNjA1NTU3fDUzNjA1NTU3fDYzODQyMzcyMTc4MDIxNDc4Ng==

Second page

To get the next page of the result we pass the forward-token from the response to the initial request.

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100&pageToken=RnwyfDUzNjA1NTU3fDUzNjA1NTU3fDYzODQyMzcyMTc4MDIxNDc4Ng==

Response headers

x-total-hits: 300

x-backward-token: QnwxfDUzNjA1NTYxfDUzNjA1NTYxfDYzODQyMzcyMTc4MDIxNDc4Ng==

x-forward-token: RnwzfDU3MzEzNDIzfDU3MzEzNDIzfDYzODQyMzcyMTc4MDIxNDc4Ng==

Third page

To get the next page of the result we pass the forward-token from the response to the previous request.

https://export.byggtjeneste.no/api/v2/items?from=2024-02-01&pageSize=100&pageToken=RnwzfDU3MzEzNDIzfDU3MzEzNDIzfDYzODQyMzcyMTc4MDIxNDc4Ng ==

Response headers

x-total-hits: 300

x-backward-token: RnwyfDUzNjA1NTQyfDUzNjA1NTQyfDYzODQyMzczMjkyNjAwMTg1Mw==

x-forward-token:

Since no forward token is present as a response header, we have all the results.