DNV Class Status API

Documentation

The API is documented using Swagger, please see API Documentation tab above.

Security

The API is secured by OAuth 2.0 with Azure AD B2C as identity provider. In order to be granted access, client apps first need to ask the identity provider for an access token. An access token should be reused in multiple http requests, as they have a validity of approximately 20 minutes.

See the Powershell script 'GenerateBearerToken.ps1' for an example implementation. It can be executed with parameters from 'secrets.txt' file. You have to implement similar logic in your client application. If using .Net, you can e.g. use the ADAL library (https://www.nuget.org/packages/Microsoft.IdentityModel.Clients.ActiveDirectory/).

The accesstoken then need to be forwared with every http request as an Authorization header: Authorization: Bearer <accessToken>

Certificate documents

In order to fetch certificate documents, you will have to handle a HTTP multipart download. A certificate can consist of multiple physical files, so a single web request can return multiple files in the http response. Carefully examine the response contents, and look out for a boundary marker (BOUNDARY_MARKER) that separates the different files, content-type for file type etc.

Example response with 2 pdf files:

HTTP/1.1 200 OK
Content-type: multipart/byteranges; boundary=BOUNDARY_MARKER

--BOUNDARY_MARKER
Content-type: application/pdf
Content-Disposition: attachment; filename=12e500c7-af90-440a-a35c-40e214f26baa.pdf; size=33474

&PDF-1.5
.... the first range
&&EOF
--BOUNDARY_MARKER
Content-type: application/pdf
Content-Disposition: attachment; filename=58e500c7-af90-440a-a35c-40e214f26bby.pdf; size=23422

&PDF-1.5
... the second range
&&EOF
--BOUNDARY_MARKER--

Data Formats

The API support both xml and json. Specify what you want with an Accept header.

Accept: application/xml
Accept: application/json

App Identification

Provide a http header describing the name of the client app. This will ease communication if the same client id is used from different applications.

X-AppName: <name>

Request Throttling

May be implemented at a later stage. Be aware of how many similar request are made to our service. You should not overflow us, but implement some sort of caching on your end.

Diagnostics

If the API is returning 401 unauthenticated

Double check with a bearer token generated from the powershell script. Remember the 'resource' argument.
Double check that the bearer token has not expired. It needs to be occationally renewed.

If API calls are intermittently failing

As you probably know, the network is not reliable (see fallacies of distributed computing), and you have to implement some kind of retry-logic on your end that takes this into account.

Polly, with exponential backoff should do the trick if you are coding in C# Microsoft documentation

For other platforms, lookup similar techniques.

Contact

maritime.customerportal@dnv.com - Support

OATH 2.0 Client Credential Grant for API endpoint

        
                [CmdletBinding()]
                Param(
                    [Parameter(Mandatory=$True,Position=1)]
                    [string]$clientId,

                    [Parameter(Mandatory=$True,Position=2)]
                    [string]$clientSecret,

                    [Parameter(Mandatory=$False,Position=3)]
                    [string]$resource = 'c916a223-f3d4-4d43-b709-cfcd77ff4a05'
                )

                $grantType = "client_credentials"
                $Uri = "https://login.microsoftonline.com/dnvglb2cprod.onmicrosoft.com/oauth2/token"

                $Body = @{
                    "grant_type" = $grantType
                    "client_id" = $clientId
                    "resource" = $resource
                    "client_secret" = $clientSecret
                }

                $token = Invoke-RestMethod -Uri $Uri -Method Post -Body $Body -ContentType "application/x-www-form-urlencoded"

                Set-Clipboard -Value $token.access_token
                Write-Output $token
                Write-Output ""
                Write-Output "Access token is copied to your clipboard"

Class Status API Guide

Get Started