Skip to content

2. Stanlab Reporting API

Jump to bottom
Danmarks Miljøportal edited this page May 27, 2021 · 2 revisions

The Stanlab Reporting API is a service interface specification for submission and reporting of samples and laboratory test. The API is implemented and hosted in the system's existing infrastructure as a standalone service or as an extension to an existing service infrastructure.

The Stanlab Reporting API is not publicly available - all requests are generated internally from the Stanlab API. For more information on how to build third party applications or integrations, please refer to the general Stanlab API.

Generel requirements and prerequisites

The requirements only apply to endpoints that will receive data from the laboratories. The laboratories must pull data periodically, and are therefore not subject to these requirements.

  • REST service supporting JSON as primary data format
  • HTTPS only
  • Public endpoint
  • Adhere to the general principles and standards of REST API implementations

Security and User Identification

The Stanlab Reporting API must be secured with bearer authorization with Stanlab STS as authority. Bearer tokens are the predominant type of access token used with OAuth 2.0 and OpenID Connect.

A Bearer Token is an opaque string, not intended to have any meaning to clients using it. Some servers will issue tokens that are a short string of hexadecimal characters, while others may use structured tokens such as JSON Web Tokens.

All tokens issued and signed by Stanlab STS will have the following claims:

Type Description Example value
sub Unique user identifier 2a4a6f75-bc15-4845-b85d-78312cb4dc24
name The user's full name Torben Wandall
email The user's email address [email protected]
vat Company, i.e. country code and country specific company ID (CVR for Danish companies) DK25798376

Hint: https://www.jwt.io for debugging JWT tokens.

API Authorization

Setting up authorization in a Stanlab Reporting API compatible service requires a valid audience and issuer. The audience is issued by Danmarks Miljøportal per request and will have the following format: reporting-api:endpoint where endpoint is the endpoint identifier issued by Danmarks Miljøportal, e.g. VanDa.

The issuer is https://stanlab-api.test.miljoeportal.dk or https://stanlab-api.miljoeportal.dk for the TEST and PROD environment respectively. More information on the security requirements can be found in the OpenID Connect discovery document that is available on /.well-known/openid-configuration relative to the issuer address. Most modern programming languages/frameworks support automatic discovery using the issuer address (authority) and will automatically set up the validation such as signing validation.

There are no required scopes as all requests to the service is authorized and managed by the Stanlab API.

OpenAPI Docs

The Stanlab Reporting API is documented using the OpenAPI Specification. OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs.

The documented API methods must be implemented and secured using the Stanlab STS as token authority.

The OpenAPI specification is available here: https://stanlab-api.test.miljoeportal.dk/openapi/stanlab-reporting-api.html. Please refer to the sample projects for guides on how to generate server stubs in your preferred programming language and framework.

Versioning

The Stanlab Reporting API is versioned in the OpenAPI specification. We recommend that third party implementations are versioned using URL Versioning by defining the version relative to the base url, i.e. https://stanlab-reporting-api.thirdparty.com/v1 for version v1. Please note that this is not a requirement.

The latest version of the API is v1.

Class Diagrams

Stanlab Reporting API Requests

reporting-api-requests

Stanlab Reporting API Responses

reporting-api-responses

Register your integration

Before your integration can be launched in production, you are obligated to setup a technical review of your application and complete the Stanlab third-party integration tests. For more information, please contact Danmarks Miljøportal support at [email protected].

Non-functional Requirements

  1. The API endpoint must be publicly available

  2. The service must reject any request on protocols other than HTTPS.

  3. The cryptographic protocol must be TLS 1.2 or higher

  4. The SSL certificate must be valid and issued by a trusted certificate authority (CA).

  5. The service must return a HTTP status code 401 for unauthorized requests, i.e.

    • Missing or incorrectly formed token
    • Invalid signature
    • Invalid token issuer
    • Expired tokens

  6. The service must return a HTTP status code 403 for forbidden requests defined by the third party.

  7. The general response time for any request should be less than 5 seconds excluding potential warm-up time.

Clone this wiki locally