Using our APIs

I just want to use an API? What are plans?

A plan is collection of API resources or subsets of resources from one or more APIs. A plan can contain a mixture of operation types from different APIs. A plan can have a common rate limit for all the resources or each resource can have a different rate limit. Rate limits specify how many requests an application is allowed to make during a specified time interval.

Use this Developer Portal to browse the different plans that are available to you and select a plan that is most suitable for your requirements. Some plans have restricted access that you must request access to use. When you submit your request, the organization is notified, the API administrator assesses your request and they might contact you for more details. Other plans are available to use straight away.

How do I see my API usage?

The number of requests, for different APIs that your application has made, are shown on your application page.

Click 'Apps' in the main menu and then click on your application. In the 'Product Subscriptions' table you will see all plans your application is subscribed to.

For each API contained in that plan you can see the usage compared to the rate limit of the plan.

How can I test an API?

It is possible to test an API from this Developer Portal.

When looking at the details of an API you will see a list of the operations contained in the API. This will show the verb and path to use for the operation.

If you click on the operation you will see more information about it, what parameters it might take, what it returns, what possible return codes it might use and what they mean.

There is also a 'Try' button on REST APIs which enables you to try the operation out direct from the Developer Portal.

If the API requires a client ID or a client secret for identification then you can specify these using your application credentials at the top of the 'Try' section.

How to use OAuth 2.0 Authorization Code Grant with PKCE?

Because some APIs involve consumer-mediated exchange of data, we follow the OAuth 2.0 protocols for authentication and authorization. The Authorization Code grant combined with the PKCE standard (RFC 7636), is used to protect resources.

Preparing for the data
  1. Client ID

    For OAuth protected APIs, please register on this API portal. Create an application and a Client ID will be generated. Subscribe the API with the application.
     
  2. Endpoints:
     

    The two endpoints are showing under the Security Section on each API’s overview page.

    • /oauth2/authorize
    • /oauth2/access_token
  3. Scope:

    The scope is showing under the Security Section on each API’s overview page.
     
  4. The PKCE flow needs to generate the below values.
     

    • code_verifier (form parameter). Contains a random string that correlates the authorization request to the token request.
    • code_challenge (query parameter). Contains a string derived from the code verifier that is sent in the authorization request and that needs to be verified later with the code verifier

    The following is an example of a code verifier and code challenge written in JavaScript:

    function base64URLEncode(words) {  

        return CryptoJS.enc.Base64.stringify(words)    

           .replace(/\+/g, '-')

           .replace(/\//g, '_')

           .replace(/=/g, '');

       }

    var verifier = base64URLEncode(CryptoJS.lib.WordArray.random(50));

    var challenge = base64URLEncode(CryptoJS.SHA256(verifier));

Getting the Authorization Code

GET …/oauth2/authorize?

  • client_id=your_client_id
  • response_type=code
  • redirect_uri=your_redirect_uri
  • code_challenge=your_code_challenge
  • code_challenge_method=S256
  • scope=<API scope>
Getting the Access Token with the Code

POST /oauth2/access_token

  • grant_type=authorization_code
  • code=your_authorization_code
  • client_id=your_client_id
  • redirect_uri=your_redirect_uri
  • code_verifier=your_code_verifier
Getting the Access Token with the Refresh Token

POST /oauth2/access_token

  • grant_type=refresh_token
  • refresh_token=your_refresh_token
  • client_id=your_client_id