Technical Overview

Introduction to the ADMIRALTY Developer Portal

The ADMIRALTY REST B2B APIs sit behind a Developer Portal. This gives the UK Hydrographic Office facility to control access, provide analytics and a platform for detailed documentation of the APIs, as well as issue tracking.

When you first arrive at the ADMIRALTY Developer Portal, you will need to sign up. Please see the Getting Started Guide for details.

Subscriptions

B2B API access is controlled by subscriptions. The Subscriptions page lists the environments you are enabled to use. For example, the first screenshot on the right shows that you have access to only the TRN subscription.

To add a subscription, you will need to raise a Customer Services Portal request. Usually the TRN subscription will be set up for you when you first sign up for the ADMIRALTY Developer Portal. A subscription to Live can be requested once you have demonstrated successful use of the provided APIs in the TRN environment.

Clicking on a subscription link on the Subscriptions page will take you to a page where you can either open the API documentation or your profile. Your profile is where you can obtain the subscription keys.

API Documentation

The API Documentation page lists all the operations that are available with an API, along with details for each operation. Selecting an operation on the left hand side will show the detail of:

• Request URL

• Request parameters If any request parameters are applicable, these will be detailed here.

• Request headers Request headers including access tokens will be detailed here.

• Request body If a request is required to have a body, the schema and examples will be documented here.

• Response Codes with sample responses. We use standard HTTP response codes, see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes for a full detailed list of standard HTTP response codes. For example, if the request was successful, we will return 200 OK, but if the authentication credentials are incorrect we will return 401 Unauthorized.

  Most responses may return either Content-Type application/json or application/zip depending on the situation. Where an application/json response is expected, the documentation will provide a sample and a schema for the response body where applicable. Errors that are not fully defined by the HTTP Status Code will return with Content-Type application/json with a json object that provides more details about the error.

• Code samples

In general, errors are defined by the HTTP response code and reason phrase. If there is additional information about the error, an error object will be returned which has a correlationId and an array of errors which gives the source and detail of each individual error.

For example, the userPass is a required parameter of the getJWTAuthUNP operation. If it was missing from a request, a 400 Bad Request will be returned with Content-Type application/json and body:

{
  "correlationId": "6c254109-8a0f-4446-8649-721775ba9de2",
  "errors": [
    {
      "source": "userPass",
      "description": "Missing or invalid encoded User:Pass."
    }
  ]
}

Try It

There is a Try It button for each operation that takes you to a page where you can specify the parameters and send a request to see what response you will get. Note, this does construct and send a request to the service and will be included in any quotas.

The Try It tool will automatically fill in the Ocp-Apim-Subscription-Key for you using your current user's subscription keys. You can select either the primary or secondary key in the Authorization section.

At the bottom of the Try It tool, you can see the HTTP request generated with all the URL parameters, headers and body required for the request. This sample request is updated as you change the parameters in the form.

Download API Definition

You can download an API definition file for the entire API by clicking the API definition button on the top right of the page. Currently you can download the API definition as either a Swagger Open API definition, or a Web Application Description Language (WADL).

Code Samples

At the bottom of the detailed description for each operation, there are code samples for using the API via 8 different languages: Curl, C#, Java, JavaScript, ObjC, PHP, Python and Ruby. These code samples are intended to give you a jump start to using the APIs using your own development stack. You will need to ensure that you update the code to include the correct parameters (e.g. for the getAVCSPermits operation, you will need to ensure that the licenceId in the url is replaced with the actual licence ID for the licence you are getting the permits for). For all operations, you will need to ensure the Ocp-Apim-Subscription-Key header is correctly populated with your subscription key.

Profile and Subscriptions

To view your profile details, click on your name in the top right and select Profile. The profile page shows:

• Profile details: email and name associated with the account
• A button to change the password associated with the account
• A link to your own analytics reports
• Subscriptions you currently have

Subscription Keys

Once you have a subscription to a product, to use the APIs you will need a subscription key. These can be found on your profile page. Each subscription will list two keys, a primary key and a secondary key. Either subscription key can be used to access the APIs. To get the subscription key, simply click Show, and copy the subscription key to your own systems.

Should you need to change either of your subscription keys for any reason (e.g. you believe it may have been compromised), simply click the regenerate button and a new subscription key will be generated.

Analytics

A report of your usage of the APIs can be found in the Analytics section of your Profile, click on the Analytics reports button on your Profile page. The Analytics give you an indication of how much you are using each of the different APIs and how many calls are returning errors. Analytics data is updated roughly every 15 minutes and you can view data for Today, Yesterday, Last 7 Days, Last 30 Days or last 90 Days.

Issues

The ADMIRALTY Developer Portal provides an issue tracker that you can use to raise technical issues during development of your solution using the B2B REST APIs. If you have a live issue, please raise a case on the Customer Services Portal. Issues are publicly visible and anyone who is logged into the system can add comments to an issue, allowing collaboration between distributors and UKHO. Please also use Issues to identify errors or omissions in the documentation.

To create an issue, click the Report Issue button on the Issues page. Here you can provide a title and detailed description of the issue and attach supporting documents as required. Please provide as much detail as possible, code samples, detailed errors (including error messages and the correlationId), etc. Remember that issues are publicly visible, so do not post your subscription keys or jwt access tokens as these should be kept secret to you.

Once an issue has been reported, users can add comments to the issue or attach additional supporting documents using the box at the bottom of the issue details page.

Environments

As a B2B Developer, you will be interested in two environments:

• Fleet Manager Training (TRN) - A TEST environment where you can place orders and download permits etc. Once you have been provided with access to https://adstrn.ukho.gov.uk/ you will be able to create test vessels and set them up with permits etc. through the Fleet Manager interface. The Fleet Manager Training environment is independent from the Fleet Manager LIVE environment.
  • REST Endpoint - https://admiralty.azure-api.net/TRN/
  • Fleet Manager UI - https://adstrn.ukho.gov.uk
• Fleet Manager Live (LIVE) - The LIVE environment where you can place orders and download permits for real products for your live licences.
  • REST Endpoint - https://admiralty.azure-api.net/live/
  • Fleet Manager UI - https://enavigator.ukho.gov.uk

The environments you have been granted access to can be found on the Subscriptions page of the ADMIRALTY Developer Portal. You will only be able to see these once you have been authorised to access the appropriate environments. If you cannot see these on the Subscriptions page, please contact your account manager.

Quotas and Throttling

To protect the service from abuse, all distributors are allocated a quota of calls. This quota has been set to a value that has been considered suitable for the level of use represented by most distributors (at the time of writing, this is 25,000 calls per 24 hour period in the LIVE environment and 2,500 calls per 24 hour period in the TRAINING environment). Once you have reached 75% of your quota, you will receive an email warning that you are approaching your usage limit. Once you exceed your quota, all further calls to the API will return HTTP 403 Quota Exceeded until the next quota period. The body of the response will tell you how long you have until your quota is refreshed:

{
    "statusCode": 403,
    "message": "Out of call volume quota. Quota will be replenished in 01:06:40."
}

in this case, the quota will be refreshed in 1 hour, 6 minutes and 40 seconds time.

To protect the level of service provided by the B2B REST APIs a throttle is in place limiting B2B REST calls. Should you exceed the rate limit, you will get HTTP 429 Too Many Requests.

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 1 seconds."
}

The throttle rates are as follows:

• The default throttle rate for operations is 2 calls every 2 seconds (per subscription)
• RegisterAENPViewer is throttled to 2 calls every 2 minutes (per subscription)
• The AVCS Online GetCapabilities call is not subject to throttling or quotas

Access Tokens (JWTs)

The B2B REST APIs are protected by JWTs (JSON Web Tokens) (see https://jwt.io/introduction/) for more information on JWT). You will need to get a token to be able to access the APIs. This can be done in several ways:

1. From the Fleet Manager web interface - go to User Management > User List, select the B2B user and click 'Generate Access Token' at the bottom of the page.
2. From the B2B API using your Fleet Manager username and password and the getJWTAuthUNP operation.
3. Renew a token via the B2B API using the getJWTAuthJWT operation.

The token will give you the same access regardless of which way you choose to generate it and will expire 1 hour from creation.

If you believe a valid JWT may have been compromised the easiest way to forcefully expire the token is to change the B2B user's password in Fleet Manager.

Token best practice

JWTs are used for B2B access as they are considered to be more secure than a username/password as they only allow B2B access. It is recommended that the B2B systems internally implement a token service that provides the same token for all requests within a renewal period (1 hour), and has a scheduled task to renew the token every 45 minutes, rather than getting a new token for every request. This will require that the system be seeded with an initial token that you can get from the Fleet Manager web interface.

HTTP Headers

Request Headers

All required request headers are detailed in the API documentation. Some of the common headers are also described here:

• Ocp-Apim-Subscription-Key - Subscription key which provides access to the APIs. Found in your Profile.
• token - This is a Fleet Manager JWT access token that identifies the Fleet Manager account and which APIs it can access. See the JWT section above for details on how to get this.

Response Headers

• X-Correlation-ID - All responses contain the X-Correlation-ID response header. This is a GUID that represents the request/response. This Correlation ID helps the UKHO track B2B requests through our systems. If you get errors that require UKHO assistance, this Correlation ID will help the UKHO to investigate the issue.

Request Timeouts

Some POST requests can take a long time to process. We recommend setting a request timeout of 330 seconds (5 and a half minutes) for POST requests to match the service settings.