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:
- An activated user account at this developer portal.
- A valid subscription for at least one product.
- 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
- 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. - 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.
- For most API operations the application needs to provide a correct
- 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
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 headerRetry-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 headerX-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