Develop and test

The developer portal contains support for testing APIs directly in a sandbox. To connect an external application will need some more preparations and also some requirements needs to be fulfilled by the application.

Prerequisites

To be able to test run the APIs you will need:

  1. An activated user account at this developer portal.
  2. A valid subscription for at least one product.
  3. For all APIs that are not open you will also need valid identity proof (BankID) locally installed.
    • The BankID application must be locally installed and configured for test.
    • Make sure not to miss step 3 in the configuration guide, mentioning the CavaServerSelector.txt file.
    • Test IDs must be downloaded and installed. To install the Test IDs you can put the p12 files in a folder called IDs in your BankID folder. You may have to create this folder. How the find the BankID folder depends on your OS and is described in the configuration guide.

Requirements for an OAuth2 authorised application

  1. The application needs to be registered in the developer portal. You will then receive your OAuth2 credentials by mail.
    • When registering your application put the redirect_uri as Url
    • The application will receive a client_id. This is globally unique and will not change over time.
    • The application will receive a client_secret. This can be re-generated if needed and differs also between environments. The one you will start with will only work for the development environment.
  2. The application must implement the OAuth2 flow Authorization Code Grant.
    • For most API operations the application needs to provide a correct scope parameter. See the API definitions for more information about this.
  3. Each API call needs to have valid values set for API Subscription Key and Access token
    • API Subscription Key is set as HTTP Header Ocp-Apim-Subscription-Key
    • Access token is set as HTTP Header Authorization
Read more about OpenID Connect/OAuth2 profile here..

Back off situations

In addition to the requirements it is also recommended for the application to handle back off situations that might occur. This will happen if too many calls are made in a given amount of time. The HTTP error code for this is 429 Too Many Requests [RFC6585]. The HTTP response header Retry-After will indicate how many seconds the application must wait until new calls can be made without being blocked, and the application should not make any more calls during this period of time.
Example: 
Retry-After: 8

Correlation ID for traceability

Responses from the API services contain the HTTP header X-COS-CORRELATION-ID. This can for example be used for debugging. Because of this it is recommended that the application is logging the correlation id in an access log.
Example: 
X-COS-CORRELATION-ID: 33b0a803-5672-4568-8a2f-1dceab3e2c67