Technical Overview
Contents
- Introduction to the ADMIRALTY API Developer Portal
- Quotas
- HTTP Headers
- Browser Based Cross Origin Resource Sharing and Key Privacy
- Branding Requirements for Developers
Introduction to the ADMIRALTY API Developer Portal
The ADMIRALTY APIs are available via our ADMIRALTY API Developer Portal. This gives ADMIRALTY the 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 API Developer Portal, you will need to sign up. Please see the ADMIRALTY API Start Up Guide for details.
Products
ADMIRALTY APIs access is controlled by subscriptions. The
Products page lists the environments you are enabled to use.
To subscribe to a Product, select the Product you require access to.
Clicking on a Product link will take you to a page where you can view the APIs within the product and subscribe.
Click the Subscribe button to personalise the Subscription name. You cannot complete your subscription of any product without reading and accepting the Terms and Conditions.
Once you have done so, you will be taken to your profile. Within this page there is a subscriptions section where you will be able to see and manage your Primary and Secondary subscription key.
Any products you have subscribed to will be visible in the APIs tab on the main menu bar.
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 subscription keys 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. For example, if the request was successful, we will return
Most responses may return either Content-Type200 OK
, but if the authentication credentials are incorrect we will return401 Unauthorized
.application/json
orapplication/zip
depending on the situation. Where anapplication/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-Typeapplication/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 an array of
errors
which gives the source and detail of each individual error.
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
GetTidalEvents
operation, you will need to ensure that the
stationId
in the url is replaced with the actual station ID you are getting the tidal events 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 an 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 gives 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 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 contact
customerservices@ukho.gov.uk.
Issues are publicly visible and anyone who is logged into the system can add comments to an issue, allowing collaboration
between developers and ADMIRALTY. 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), etc. Remember that issues are publicly visible, so don't post your subscription keys as these should be kept secret.
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.
Quotas
To protect the service from abuse, all developers are allocated a quota of calls. Please see the Terms and Conditions of
the relevant product for quota limits. 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."
}
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.
Browser Based Cross Origin Resource Sharing and Key Privacy
All modern browsers enforce security when data for www.yourwebsite.com is provided by www.someoneElsesWebsite.com.
As your key is embedded in your application / webpage, it may be at risk of others to use it.
By putting the API-accessing code on your server, you can avoid the browsers triggering this feature.
The diagram on the right shows that when your key is embedded in your server layer, it is protected from others by the server’s security and your authentication. End users do not see your key, and thus cannot use your quota.
To find out more, search for CORS or Cross Origin Resource Sharing.
Branding Requirements for Developers
Where technically possible, the following acknowledgement shall be included, such that it is visible to end-users:
Contains ADMIRALTY® tidal data:
© Crown Copyright and database right.
The font is Arial and minimum 12 px text size. The statement should be split onto two lines. This font colour can
either be ADMIRALTY blue, black, or white. It can also be transparent if the background makes the statement visible.
PANTONE 654
100C 73M 10Y 50K
9R 49G 91B
#09315B