Calling an API – HOW-TO

 

 

Most of the APIs will require form of authentication and authorization. If the used API requires no authorization, you can skip the next chapter and continue with the chapter “Calling an API”

 

Token Service

Token service is used to retrieve an access token used to authorize a web service client. The token service is part of the OAuth 2.0 protocol. For most of the APIs the “client_credentials” OAuth profile is used authenticating the application client.

 

 

Registering an application

 

To use any API there must be a client application registered.

 

 

 

Fill in a name, description and allowed quota.

 

 

 

Create a subscription – permission of the application to use the API

 

 

 

 

 

 

 

Generating an access token

 

 

 

It is possible to create a token from the API Store console or using a token web service

 

 

Generating an access token using the API Store console

 

 

Creating the token from the API Store console is recommended for development purposes or for creating a permanent “client credentials” (application) token.

 

 

 

 

 

When specifying a Validity Period it is possible to generate a permanent application token by using value -1. When creating a new access token from this console will revoke the existing access token.

 

 

 

Generating an access token using the Token web service

 

The API Manager needs to authenticate and authorize only the client application (not the end users), therefore the client credentials OAuth 2.0 profile is used.

 

curl -X POST \

     -d "grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret" \

     https://api.brussels/api/token

 

 

> POST /api/token HTTP/1.1

> User-Agent: curl/7.29.0

> Host: api.brussels

> Accept: */*

> Content-Length: 111

> Content-Type: application/x-www-form-urlencoded

 

grant_type=client_credentials&client_id=Tm082NgwZcAGpIghHjJnUAiq2OEb&client_secret=NE1OZpRWvB9SMsIZTCe4zzJyC2sb

 

 

Where the consumer-key and consumer-secret values are taken from the application settings

 

 

 

Token service response sample:

 

{

  "access_token":"eb7c269b-3ebf-31b8-b5b1-a542aac8af56",

  "scope":"am_application_scope default",

  "token_type":"Bearer",

  "expires_in":3600

}

 

The client application should cache the application access token and it must track validity of the token. Once the access token is expired or revoked, new access token should be requested.

 

 

Access token scope

 

Some APIs may require special permissions (based on roles) - scope. To request a token with specific token is possible through the API DEV console or Token API service:

 

 

curl -X POST \

     -d "grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret&scope=scope_name" \

     https://api.brussels/api/token

 

 

Revoking an access token

 

An access token can be revoked using the revocation service

 

 

curl -X POST -d  "token=existing_token&grant_type=client_credentials&client_id=consumer-key&client_secret=consumer-secret" \

     https://api.brussels/api/revoke

 

Alternative:

curl -X POST -d  "token=existing_token" \

     -H "Authorization: Basic Base64(consumer-key:consumer-secret)" \

     https://api.brussels/api/revoke

 

 

 

 

 

Calling an API

 

 

Testing API services

 

It is possible to test the API and its usage using the API Store console

 

The authorized application and its key set (production or sandbox) needs to be selected once an access token is generated.

 

 

 

 

 

 

Using API Services

 

Example call:

 

 

curl -X GET \

    -H 'Accept: application/xml' \

    -H 'Authorization: Bearer 4717fa00-cc20-3414-b3b1-bc869b5eb4aa' \

   'https://api.brussels/api/agenda/v0.0.1/events'

 

 

 

Important headers: