From 77c9315be6d2ecf5a715cf13b3f4f933d5088ae8 Mon Sep 17 00:00:00 2001 From: Tony Heap Date: Mon, 26 Nov 2018 10:32:39 +0000 Subject: [PATCH] APIS-3682 Updates to reference guide --- .../views/reference.scala.html | 487 +++++++++--------- 1 file changed, 239 insertions(+), 248 deletions(-) diff --git a/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html b/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html index 045100ce..bd70762d 100644 --- a/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html +++ b/app/uk/gov/hmrc/apidocumentation/views/reference.scala.html @@ -32,20 +32,21 @@
@@ -62,22 +63,27 @@

API access

@applicationConfig.productionApiBaseUrl
-
-

Network access

-

You might need to configure your network so your software can access our API Platform and the authorisation journey for - user-restricted endpoints. - If your software is installed on end user devices, they might also need to configure their own network.

-

We have fixed domain names, but cannot provide static IP addresses, so you need to configure your network - access in your proxy, not your firewall.

-

Configure your proxy to allow full access to the following domains, including HTTP GET, POST, PUT and DELETE.

-

For testing in sandbox:

- 
-@applicationConfig.sandboxApiHost
-@applicationConfig.sandboxWwwHost
-

For production use:

- 
-@applicationConfig.productionApiHost
-@applicationConfig.productionWwwHost
+
+

Browser support for OAuth 2.0

+ +

The OAuth 2.0 authorisation + + journey is designed to work with most modern browsers as per the list specified on + + Designing for different browsers and devices, including mobile devices and tablets. +

+

If you are using the Microsoft Web Browser Control embedded browser for the + authorisation journey, be aware that by default this will operate in IE7 compatibility mode which we do not + formally support. For details of one way to handle this, see + + Controlling WebBrowser Control Compatibility (opens in a new tab). +

+
+ +
+

Coding in the open

+

The HMRC Developer Hub, the underlying API Platform and some of the APIs are coded in the open, as per the @Link.toExternalPage(url = "https://www.gov.uk/service-manual/service-standard/make-all-new-source-code-open", value = Some("GOV.UK Digital Service Standard (opens in a new tab)"), dataAttributes = Some(Map("journey-click" -> "external-link:click:GOV.UK Digital Service Standard"))).toHtml.

+

The source code is available at @Link.toExternalPage(url = "https://github.com/hmrc", value = Some("https://github.com/hmrc (opens in a new tab)"), dataAttributes = Some(Map("journey-click" -> "external-link:click:https://github.com/hmrc"))).toHtml. For more details, please contact us.

@@ -125,20 +131,13 @@

Common data types

-
-

HTTP redirection

-

Our API Platform uses HTTP redirection if resources move permanently or temporarily.

-

Redirection responses have a Location header with the resource's new URI.

-
-
-

Common API Errors

+

Errors

-

- Error responses from APIs (but not the OAuth 2.0 authorisation procedure) have a 4xx or 5xx HTTP status code and a consistently formed JSON or XML body, including: -

+

Errors during the authorisation process use the format specified in the OAuth 2.0 RFC.

+

Errors from APIs have a 4xx or 5xx HTTP status code and a consistently formed JSON or XML body, including:

@@ -198,7 +197,10 @@

Common API Errors

<reactivationTimestamp>1431448640718</reactivationTimestamp> </error> -

These error responses are common across all APIs:

+ +

If the response body of an error is not in the above format or the OAuth 2.0 error format, the error has probably not come from us. One possible cause is a network access issue.

+

Some API errors are common across all APIs; others are API-specific.

+

The following tables list the common API errors. You can find API-specific errors in the API documentation.

@@ -211,11 +213,11 @@

401 (Unauthorized)

- + - + @@ -243,10 +245,6 @@

403 (Forbidden)

- - - - @@ -326,7 +324,7 @@

429 (Too Many Requests)

- + @@ -405,61 +403,6 @@

504 (Gateway Timeout)

No OAuth token supplied for user-restricted or application-restricted resourceNo OAuth token supplied for user-restricted or application-restricted endpoint MISSING_CREDENTIALS
Invalid OAuth token supplied for user-restricted or application-restricted resource (including expired token)Invalid OAuth token supplied for user-restricted or application-restricted endpoint (including expired token) INVALID_CREDENTIALS
Request done with HTTP HTTPS_REQUIRED
Production tokens used for Beta APIAPI_NOT_IN_PRODUCTION
The OAuth token's application is not subscribed to the API RESOURCE_FORBIDDEN
The application has reached its maximum rate limitThe application has reached its maximum rate limit MESSAGE_THROTTLED_OUT
- -
- - -

You can find API-specific error responses in the API documentation.

-

Note that the OAuth 2.0 process conforms with the error format specified in the OAuth 2.0 RFC. See authorisation for more information on the process.

- -
- -
- -
- -

Rate limiting

- -

We limit the number of requests each application can make. This protects our service against excessive use and Denial-of-Service attacks, and also encourages you to use our APIs efficiently.

-

We set limits based on anticipated loads and peaks. Our standard limit is 150 requests per minute per application.

-

If you reach this limit you’ll get a 429 Too Many Requests response code.

-

If you continually hit this rate limit, contact us to discuss your application design and whether it’s appropriate to raise your rate limit.

- -
- -
- -

Scopes

- -

When your application needs to access resources on behalf of a user, the Developer Hub uses the OAuth 2.0 framework to grant and manage such an authority.

- -

This authority is granted in terms of OAuth 2.0 ‘scopes’. Each 'scope' relates to one or more endpoints.

- -

When your application requests an OAuth 2.0 Bearer token, it must specify the scope(s) which the token should be granted for.

- -

These are translated to human-readable descriptions that are shown to the user before they grant authority. This makes sure the user understands and gives access to your application.

- -

The scope for each user-restricted endpoint is defined in the API documentation.

- -

For details about OAuth 2.0 and scopes, see authorisation.

- -
- -
- -

Versioning

- -

When an API changes in a way that's backwards-incompatible, the version of the API will be bumped.

- -

You can request a specific version of an API by using an Accept header with a media type of:

- - 
application/vnd.hmrc.[version]+[content-type]
- -

For example:

- - 
application/vnd.hmrc.1.0+json
- -

Media types are specific to each resource, which lets them change separately from one another.

@@ -477,7 +420,7 @@

Compulsory Information

To find out when supplying the data becomes compulsory for each API, read its - API documentation. + API documentation.

Header Contents

@@ -524,239 +467,269 @@

Header Contents

Gov-Client-Public-IP -

The public IP address of the originating client machine.

-

For example, 198.51.100.0

+ The public IP address of the originating client machine. +

+ For example, 198.51.100.0 Gov-Client-Public-Port -

The port component of the Gov-Client-Public-IP.

-

For example, 12345

+ The port component of the Gov-Client-Public-IP. +

+ For example, 12345 Gov-Client-Device-ID -

- A consistent ID representing the originating client machine. This depends on the context. - For an installed application of batch processes, this is the MAC address of the device’s network adapter. - For a web browser, this is a unique value stored in a long term cookie. -

-

For example, beec798b-b366-47fa-b1f8-92cede14a1ce

+ A consistent ID representing the originating client machine. This depends on the context. + For an installed application of batch processes, this is the MAC address of the device’s network adapter. + For a web browser, this is a unique value stored in a long term cookie. +

+ For example, beec798b-b366-47fa-b1f8-92cede14a1ce Gov-Client-User-ID -

- The identifier that the customer used to login to the client machine, and/or the software vendor’s software or website. Provide multiple identifiers as a comma-delimited list. Use N/A if no identifiers are available. -

-

- For example, - alice_desktop, - alice_online21 (for method D) - user123 (for all other methods) -

+ The identifier that the customer used to login to the client machine, and/or the software vendor’s software or website. Provide multiple identifiers as a comma-delimited list. Use N/A if no identifiers are available. +

+ For example, + alice_desktop, + alice_online21 (for method D) + user123 (for all other methods) Gov-Client-Timezone -

Timezone of the clock on the client machine.

-

For example, GMT+3

+ Timezone of the clock on the client machine. +

+ For example, GMT+3 Gov-Client-Local-IP -

Internal private IP address used by the client machine.

-

For example, 10.1.2.3

+ Internal private IP address used by the client machine. +

+ For example, 10.1.2.3 Gov-Client-Screen-Resolution -

Methods A to E only.

-

Screen resolution of the client machine in pixels.

-

For example, 1920x1080

+ Methods A to E only. +

+ Screen resolution of the client machine in pixels. +

+ For example, 1920x1080 Gov-Client-Window-Size -

Methods A to E only.

-

Size of the application or browser window on the client machine in pixels.

-

For example, 1256x803

+ Methods A to E only. +

+ Size of the application or browser window on the client machine in pixels. +

+ For example, 1256x803 Gov-Client-Colour-Depth -

Methods A to E only.

-

Colour depth of the client machine in bits per pixel.

-

For example, 24

+ Methods A to E only. +

+ Colour depth of the client machine in bits per pixel. +

+ For example, 24 Gov-Client-User-Agent -

For methods A to D and F: "<OS Family>/<OS Version> (<Manufacturer> <Model>)"

-

For example, Android/6.0.1 (Samsung Galaxy S4)

-

For method E: the User-Agent reported by the browser.

-

For example, Mozilla/4.0 (compatible; MSIE 5.5; Windows 98)

+ For methods A to D and F: "<OS Family>/<OS Version> (<Manufacturer> <Model>)". +

+ For example, Android/6.0.1 (Samsung Galaxy S4) +

+ For method E: the User-Agent reported by the browser. +

+ For example, Mozilla/4.0 (compatible; MSIE 5.5; Windows 98) Gov-Client-Browser-Plugins -

Method E only.

-

List of installed browser plugins.

-

For example, - Shockwave Flash, - Chromium PDF Viewer -

+ Method E only. +

+ List of installed browser plugins. +

+ For example, + Shockwave Flash, + Chromium PDF Viewer Gov-Client-Browser-JS-User-Agent -

Method E only.

-

User Agent value as reported by Javascript.

-

- For example, - 

+                        Method E only.
+                        


+                        User Agent value as reported by Javascript.
+                        


+                        For example,
+                        
 Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like
 Mac OS X; en-us) AppleWebKit/531.21.10
 (KHTML, like Gecko) Mobile/7B405

-                        

                     
                 
                 
                     Gov-Client-Browser-Do-Not-Track
                     
-                        
Method E only.

-                        
Whether the browser has set the Do Not Track flag or not, if the client machine is using a web browser.

-                        

-                            For example,
-                            false
-                        

+                        Method E only.
+                        


+                        Whether the browser has set the Do Not Track flag or not, if the client machine is using a web browser.
+                        


+                        For example,
+                        false
                     
                 
                 
                     Gov-Client-Multi-Factor
                     
-                        
Method E only.

-                        

-                          Details about the multi-factor authorisation that the vendor requires their user to pass before
-                          using their application. This should be constructed as
-                          "<type>;<UTC timestamp>;<unique reference (hashed or not)>".
-                        

-                        

-                                <type> is a short, human readable tag describing the method of two factor authorization,
-                                for example SMS, MOBILEAPP, or GOOGLEAUTH.
-                        

-                        

-                                <UTC timestamp> records the time of the last successful second factor prompt.
-                        

-                        
 <unique reference> identifies a single second factor, for example, a salted hash
-                            (securer version) of a phone number used for SMS or an identifier linked to a TOTP secret
-                            (not the secret itself). The intention is to recognise the same second factor being used
-                            across API calls.
-                        

-                        

-                            For example,
-                            SMS;2017-04-21T13:23:42Z;c672b8d1ef56ed28
-                        

+                        Method E only.
+                        


+                        Details about the multi-factor authorisation that the vendor requires their user to pass before
+                        using their application. This should be constructed as
+                        "<type>;<UTC timestamp>;<unique reference (hashed or not)>".
+                        


+                        <type> is a short, human readable tag describing the method of two factor authorization,
+                        for example SMS, MOBILEAPP, or GOOGLEAUTH.
+                        


+                        <UTC timestamp> records the time of the last successful second factor prompt.
+                        


+                        <unique reference> identifies a single second factor, for example, a salted hash
+                        (securer version) of a phone number used for SMS or an identifier linked to a TOTP secret
+                        (not the secret itself). The intention is to recognise the same second factor being used
+                        across API calls.
+                        


+                        For example,
+                        SMS;2017-04-21T13:23:42Z;c672b8d1ef56ed28
                     
                 
                 
                     Gov-Vendor-Version
                     
-                        

-                            The vendor’s software version.

-                            This is the installed application version, or the software version of the backend Application Server.
-                        

-                        

-                            Where there are multiple versions, these should be appended as a comma delimited list as new
-                            values are seen in the request.
-                        

-                        

-                            For example, for methods C and D there will be an installed application (with a version), and a
-                            backend server (also with a version).
-                        

-                        

-                            For example,
-                            1.2.3 build 4286 (for methods A, B and F)
-                            2.2.2, v3.8 (for methods C, D and E)
-                        

+                        The vendor’s software version.

+                        This is the installed application version, or the software version of the backend Application Server.
+                        


+                        Where there are multiple versions, these should be appended as a comma delimited list as new
+                        values are seen in the request.
+                        


+                        For example, for methods C and D there will be an installed application (with a version), and a
+                        backend server (also with a version).
+                        


+                        For example,
+                        1.2.3 build 4286 (for methods A, B and F),
+                        2.2.2, v3.8 (for methods C, D and E)
                     
                 
                 
                     Gov-Vendor-Instance-ID
                     
-                        

-                            An identifier unique to a specific installation of the vendor’s software, either on a client
-                            device or on a backend Application Server.

-                            This could be a license key, or else some value generated when the application is installed.
-                            This can be hashed.
-                        

-                        

-                            Where there are multiple instance IDs, these should be appended as a comma delimited list as new
-                            values are seen in the request.
-                        

-                        

-                            For example,
-                            fa7c484c-d8cf-4f8a-a39c-54a2a4c04bc6 (for methods A, B, E and F)
-                            01ecef0967a, app3 (for methods C and D)
-                        

+                        An identifier unique to a specific installation of the vendor’s software, either on a client
+                        device or on a backend Application Server.

+                        This could be a license key, or else some value generated when the application is installed.
+                        This can be hashed.
+                        


+                        Where there are multiple instance IDs, these should be appended as a comma delimited list as new
+                        values are seen in the request.
+                        


+                        For example,
+                        fa7c484c-d8cf-4f8a-a39c-54a2a4c04bc6 (for methods A, B, E and F),
+                        01ecef0967a, app3 (for methods C and D)
                     
                 
                 
                     Gov-Vendor-Public-IP
                     
-                        
The public IP address that the customer’s machine used to send requests to the software vendor.

-                        

-                            This will be the same as the Gov-Client-Local-IP for direct options A, B and F.

-                            For other indirect options, C, D and E, it should be the first IP address that the client request
-                            hits within the vendor’s network.
-                        

-                        

-                            This may be an IP address of a Web Application Firewall, or a DDOS Protection Service, or a load
-                            balancer that the vendor’s DNS record resolves to.
-                        

-                        
For example, 203.0.113.6

+                        The public IP address that the customer’s machine used to send requests to the software vendor.
+                        


+                        This will be the same as the Gov-Client-Local-IP for direct options A, B and F.
+                        


+                        For other indirect options, C, D and E, it should be the first IP address that the client request
+                        hits within the vendor’s network.
+                        


+                        This may be an IP address of a Web Application Firewall, or a DDOS Protection Service, or a load
+                        balancer that the vendor’s DNS record resolves to.
+                        


+                        For example, 203.0.113.6
                     
                 
                 
                     Forwarded
                     
-                        
Methods C to E.

-                        
The Forwarded header is created and appended to by any intermediary server that handles the
-                            request in an unencrypted form. This should be a small list as most communications will be via HTTPS.
-                        

-                        

-                            If no value is defined, and the request came from the Gov-Client-Local-IP,
-                            then add :
 "for=<Gov-Client-Local-IP>;by=<current IP>"
-                        

-                        

-                            If no value is defined, and the request came from some other IP address (not the
-                            Gov-Client-Local-IP), then add :

-                            "for=<Gov-Client-Local-IP>, for=<IP request came from>;by=<current IP>"
-                        

-                        

-                            If the value is defined, then append the following to the existing value :

-                            ", for=<IP request came from>;by=<current IP>"
-                        

-                        

-                            For more details on this header field, see IETF RFC7239 (opens in a new tab).

-                        
For example, for=10.1.2.3;by=198.51.100.0

+                        Methods C to E.
+                        


+                        The Forwarded header is created and appended to by any intermediary server that handles the
+                        request in an unencrypted form. This should be a small list as most communications will be via HTTPS.
+                        


+                        If no value is defined, and the request came from the Gov-Client-Local-IP,
+                        then add :
 "for=<Gov-Client-Local-IP>;by=<current IP>"
+                        


+                        If no value is defined, and the request came from some other IP address (not the
+                        Gov-Client-Local-IP), then add :

+                        "for=<Gov-Client-Local-IP>, for=<IP request came from>;by=<current IP>"
+                        


+                        If the value is defined, then append the following to the existing value :

+                        ", for=<IP request came from>;by=<current IP>"
+                        


+                        For more details on this header field, see IETF RFC7239 (opens in a new tab).
+                        


+                        For example, for=10.1.2.3;by=198.51.100.0
+
+

HTTP redirection

+

Our API Platform uses HTTP redirection if endpoints move permanently or temporarily.

+

Redirection responses have a Location header with the endpoint's new URI.

+
+ +
+

Network access

+

You might need to configure your network so your software can access our API Platform and the authorisation journey for + user-restricted endpoints. + If your software is installed on end user devices, they might also need to configure their own network.

+

We have fixed domain names, but cannot provide static IP addresses, so you need to configure your network + access in your proxy, not your firewall.

+

Configure your proxy to allow full access to the following domains, including HTTP GET, POST, PUT and DELETE.

+

For testing in sandbox:

+ 
+@applicationConfig.sandboxApiHost
+@applicationConfig.sandboxWwwHost
+

For production use:

+ 
+@applicationConfig.productionApiHost
+@applicationConfig.productionWwwHost
+
+ +
+ +

Rate limiting

+ +

We limit the number of requests each application can make. This protects our service against excessive use and Denial-of-Service attacks, and also encourages you to use our APIs efficiently.

+

We set limits based on anticipated loads and peaks. Our standard limit is 150 requests per minute per application.

+

If you reach this limit you’ll get a response with an HTTP status of 429 (Too Many Requests).

+

If you continually hit this rate limit, contact us to discuss your application design and whether it’s appropriate to raise your rate limit.

+ +
+

Redirect URIs

We use redirect URIs to send the user back to your application after successful (or unsuccessful) authorisation, @@ -833,20 +806,38 @@

Examples

-
-

OAuth 2.0 browser support

+
-

The OAuth 2.0 authorisation +

Scopes

+ +

When your application needs to access API endpoints on behalf of a user, the Developer Hub uses the OAuth 2.0 framework to grant and manage such an authority.

+ +

This authority is granted in terms of OAuth 2.0 'scopes'. Each 'scope' relates to one or more endpoints.

+ +

When your application requests an OAuth 2.0 Bearer token, it must specify the scope(s) which the token should be granted for.

+ +

These are translated to human-readable descriptions that are shown to the user before they grant authority. This makes sure the user understands and gives access to your application.

+ +

The scope for each user-restricted endpoint is defined in the API documentation.

+ +

For details about OAuth 2.0 and scopes, see authorisation.

+ +
+ +
+ +

Versioning

+ +

Request the version of the API you want to use by including an Accept header with a media type of:

+ + 
application/vnd.hmrc.[version]+[content-type]
+ +

For example:

+ + 
application/vnd.hmrc.1.0+json
+ +

We release backwards-compatible changes in the same version, so you don't need to change your Accept header. We release backwards-incompatible changes in a new version, and you must change your Accept header to use it.

- journey is designed to work with most modern browsers as per the list specified on - - Designing for different browsers and devices, including mobile devices and tablets. -

-

If you are using the Microsoft Web Browser Control embedded browser for the - authorisation journey, be aware that by default this will operate in IE7 compatibility mode which we do not - formally support. For details of one way to handle this, see - - Controlling WebBrowser Control Compatibility (opens in a new tab). -

+ }