Technical Overview

About the Web API

Through the APIs your applications can retrieve and update content in ArtDatabankens different systems. To access certain data the application must get the users permission to access the data.

The different API:s

Species Observations (www.artportalen.se)

The APIs are available in two forms. The first form includes solely read (out) APIs (used for searching observations in Artportalen), while the other form contains both read and write (in) APIs (for searching and reporting data to Artportalen. Both forms are available in test (sandbox) and production environments. Applications (apps) are first developed in the test environment and afterwards moved to the production environment after approval by ArtDatabanken.

Species information (www.artfakta.se)

This API returns species related information from ArtDatabanken’s Artfakta platform. Applications are developed directly in the production environment. There is no test environment.

Links

API Documentation
Om ArtDatabankens API:er (in Swedish)
API för inrapportering (in Swedish)

Security

Subscription key

To access any of the API:s at Artdatabanken an subscription key must be added to your request. Key are received by signing-in and requesting a subscription to any of the ArtDatabanken products. The keys are than found in your profile in the developer portal.

A key must always be added to any requests to the API:s. The key should be added as a HTTP request header:

Ocp-Apim-Subscription-Key: {key}

Authorization

Requests to the Artdatabanken Web API:s may also require authorization, ie the end user must have granted permission for an application to access/change data on behalf of the user. The application requests the permission by redirecting the user to the ArtDatabanken Login Service web application, which returns an authorization token to the application. To prove that the user was granted permission for the application, an HTTP header, with a valid authorization token, should be sent in each request to the API by the application.

Authorization: Bearer {authentication token}

OAuth 2 and OpenID Connect

The Web API uses the OAuth 2 and OpenID Connect standards during authorization.

As the first step towards authorization, you will need to receive your unique client ID and client secret key from ArtDatabanken to use in the authorization flows. You will also need to specify the return URL where the token should be delivered on login. Contact support to exchange authorization details.

Supported Authorization Flows

Implicit Grant flow

Implicit grant flow is implemented when clients are regarded as “insecure”, ie web clients, mobile apps etc.


Authorization Code Grant Flow

This method is suitable for long-running applications which the user logs into once. It provides an access token that can be refreshed. Since the token exchange involves sending your secret key, this should happen on a secure location, like a backend service, not from a client like a browser or mobile app.


Both of these flows are described in RFC-6749.

API

Web API endpoint documentation

The different API endpoints are documented here.

Requests

The Web API is based on the REST principles: data resources are accessed via standard HTTPS requests in UTF-8 format to an API endpoint. Where possible, the API strives to use the appropriate HTTP verbs for each action:

VERB DESCRIPTION
GET Used for retrieving resources
POST Used for creating resources
PUT Used for changing/replacing resources or collections
DELETE Used for deleting resources

Responses

All data is received as a JSON object.

Response Status Codes

The API uses the following response status codes:

STATUS CODE DESCRIPTION
200 OK – The request has succeeded. The client can read the result of the request in the body and the headers of the response.
401 Unauthorized – The request requires user authentication or – if the request included authorization credentials – authorization has been denied access for those credentials.
... And perhaps a bunch of others…