Cloud Blog

APIs to control your API Management

In WSO2 API Cloud, everything you do through the web user interface can also be done programmatically via APIs. Detailed API reference can be found in the API Cloud’s Product APIs documentation.

Today I will show you just a quick example on how you can use Publisher’s RESTful APIs to get a list of APIs published (for all other operations you would use a similar approach and simply other REST resources from the API reference).

1. Register client

1.1. Obtain your organization-qualified ID

The first thing we need to do is register our API client and obtain the consumer ID and consumer secret values.

The most important piece of information that you need for that is your domain-qualified ID in WSO2 Cloud. This is your email address @ your Organization Key. You can find your Organization Key by clicking Organization on the 9-dot menu at the top right of the cloud interface.

For example, on the screenshot below, my Organization Key is wso2dmitry2639:

With my email address dmitry@wso2.com, this gives me the qualified ID of dmitry@wso2.com@wso2dmitry2639.

1.2. Create registration json

This is just a payload.json file that would have the ID that you have just obtained. In my case that would be:

{
  "callbackUrl": "www.wso2.com",
  "clientName": "rest_api_publisher",
  "tokenScope": "Production",
  "owner": "dmitry@wso2.com@wso2dmitry2639",
  "grantType": "password refresh_token",
  "saasApp": true
}

Save that text file as payload.json.

1.3. Encode your credentials

Now you need to take the qualified ID from step 1.1, add a colon (:), add your password and do Base 64 encoding for that string. For example, if my password was P@ssw0rd, I would have needed to encode dmitry@wso2.com@wso2dmitry2639:P@ssw0rd and that would have given me: ZG1pdHJ5QHdzbzIuY29tQHdzbzJkbWl0cnkyNjM5OlBAc3N3MHJk

1.4. Register the client

Now you can just run this curl command in the folder that has your payload.json from step 1.2:
curl -X POST -H "Authorization: BasicZG1pdHJ5QHdzbzIuY29tQHdzbzJkbWl0cnkyNjM5OlBAc3N3MHJk" -H "Content-Type: application/json" -d @payload.json https://api.cloud.wso2.com/client-registration/v0.11/register/v0.11/register

This will give you an output like:

{
  "clientId":"O7buGR5fMVMuNBFF",
  "clientName":"dmitry-AT-wso2.com_rest_api_publisher",
  "callBackURL":"www.wso2.com",
  "clientSecret":"A3mYNQjHDsXX_T1",
  "isSaasApplication":true,
  "appOwner":"dmitry@wso2.com@wso2dmitry2639",
  "jsonString":"
     {
         \"grant_types\":\"password refresh_token\",
         \"redirect_uris\":\"www.wso2.com\",
         \"client_name\":\"dmitry-AT-wso2.com_rest_api_publisher\"
     }"
}

This response has everything we need: clientId is your consumer key and clientSecret is your consumer secret.

2. Obtain OAuth token

2.1 Encode consumer key and consumer secret

Now we need to take the clientId and clientSecret values, put a colon between them, and base 64 encode that string. In my case, I need to encode O7buGR5fMVMuNBFF:A3mYNQjHDsXX_T1.

When I do that, I get TzdidUdSNWZNVk11TkJGRjpBM21ZTlFqSERzWFhfVDE=

2.2 Find your scope

In the documentation page for the method you want to call, find which scope it needs. I just want to use Retrieve/Search API and this method requires apim:api_view scope.

2.3 Request the token

Now you have everything you need to get the OAuth token. Simply run this (with your own ID, encoded keys, and scope):

curl -k -d "grant_type=password&username=dmitry@wso2.com@wso2dmitry2639&password=P@ssw0rd&scope=apim:api_view" -H "Authorization: BasicTzdidUdSNWZNVk11TkJGRjpBM21ZTlFqSERzWFhfVDE=" https://gateway.api.cloud.wso2.com/token

You then get a response like that:

{
  "access_token":"89c12aab-6f0e-3c3b-8409-d186670ec73c",
  "refresh_token":"2cba2b65-d56a-25a7-a742-1a12345d123",
  "scope":"apim:api_view",
  "token_type":"Bearer",
  "expires_in":3600
}

access_token is the OAuth key you can use for your calls.

3. Use the APIs

Now you can just take that access token and use it with the API call that you pick from the reference page. In my case, for the token that I got, to get a list of all APIs, I would call:

curl -k -H "Authorization: Bearer 89c12aab-6f0e-3c3b-8409-d186670ec73c" https://api.cloud.wso2.com/api/am/publisher/v0.11/apis

I then get a response like:

{"count":1,
"next":"",
"previous":"",
"list":[
  {"id":"50b7213d-21d2-1234-840c-34e12d778a61",
  "name":"WorldBank",
  "description":"Country data API",
  "context":"/t/wso2dmitry2639/wb",
  "version":"1.0.0",
  "provider":"dmitry@wso2.com@wso2dmitry2639",
  "status":"PUBLISHED",
  "thumbnailUri":"/apis/50b7213d-21d2-1234-840c-34e12d778a61/thumbnail"}
]
}

For my tutorial, I picked just one simple call to list the APIs. Full reference has dozens of methods that you can use to completely bypass our user interfaces and perform any API management operations programmatically.

Check out API Cloud’s Product APIs documentation and let us know what you think.

Put your SOAP to REST

API management is about selectively, securely, and conveniently exposing internal functionality to the outside world. Quite often external consumption model and internal representation of APIs do not match and this is when API gateways shine efficiently translating one representation into the other on the fly.

Exposing SOAP web-services of internal enterprise systems as lightweight external REST APIs is a very frequent case of that. Here’s what it looks like:

  1. External REST API is called. Parameters are typically passed as parts of the URL path, query parameters, headers, or JSON payload. Authentication typically happens via OAuth2.
  2. API gateway receives the call, checks OAuth keys, enforces various policies such as throttling and scopes, records the call for analytics and monetization purposes, and creates a SOAP call with the new payload based on expected format and parameters, then passes the call to the backend.
  3. The backend would typically use some other form of authentication such as basic or digest authentication, mutual SSL, and IP whitelisting.
  4. When the backend responds, the gateway would do another transformation of the response to the format that the web or mobile client expects – typically JSON.

WSO2 API Cloud makes this process easy and efficient. See our documentation for details:

See also this blog post by Shenavi:

Categories

Recent Posts

Most Popular Posts