How to Call an API in WSO2

Owned by Ashish Pandit
Last updated: Jun 13, 2017
4 min read

This guide will help you get started consuming APIs in WS02.

Step-by-step guide
  1. Create a WSO2 Application
    1. Follow the guide for creating a WSO2 Application /wiki/spaces/APIArchive/pages/22675612.
    2. An Application will represent your implementation of consuming the API. This could be in the form of a front-end Single Page Application (SPA), a separate service that needs data from a set of APIs, or just a curl command.
  2. Subscribe Application to desired API
    1. Follow the guide to subscribe to a WSO2 managed API /wiki/spaces/APIArchive/pages/22675615.
    2. A WSO2 Application can have multiple subscriptions. The WSO2 Application should subscribe to all the APIs needed for the implementation application (SPA, etc.) to function. Having all the needed APIs subscribed under one WSO2 Application will simplify the use of the OAuth access token described below.
  3. Generate Application keys
       A WSO2 Application may have two sets of credentials (or keys). These keys are used to retrieve an access token, which your code will use to make HTTP requests to your subscribed API. (In WS02, the "TryIt" feature performs this kind of request.) The Production keys are associated with the Production endpoint of a subscribed API, and the Sandbox keys are associated with the Sandbox endpoint of a subscribed API. 





    1. Notice that the Production/QA Endpoint should be different than the DEV Endpoint. The Production Endpoint represents the service that is production-ready, whereas the Sandbox Endpoint represents a staging service for testing and verification, and/or development.
    1. Once you have generated your Production and/or Sandbox keys, you will use them to access data from an API. The two examples below each show a different method of how to do this.
  4. Use an Access Token to make a curl request to your subscribed API

    1. You can now make a valid request to your subscribed API by taking the "Access Token" as shown above and using it in an HTTP request.
    2. The "Access Token" represents your authorization to access the API. WSO2 API Manager would return a 403 HTTP response code if you did not provide an access token or if the access token was not a valid token generated from your WSO2 Application keys.
    3. Add an "Authorization" header in your request with the value: "Bearer <Access Token>" (except replacing <Access Token> with an actual value).

    4. Test that the token works and everything is wired up right by using curl.

       curl -H "Authorization :Bearer 441aae1cb1ad1584cec2334d61eb25b5" https://api-qa.ucsd.edu:8243/webreg/2.1.0/schedule/editEnroll

      Replace the token with the bearer token you just (re)generated.  You should get a response from the WebReg api indicating "Insufficient Parameters" or something similar.

      Note: if you are skipping the Load Balancer and accessing the gateway directly, curl will complain about the certificate it is using.  Add the -k option to prevent SSL certificate verification..

       
    5. There you have it! You should see the expected content from your subscribed API.
  5. Use the "TryIt" feature to make a request to your subscribed API
    1. Instead of performing a curl request, you can access your subscribed API via the "TryIt" feature found on the API console within the API store. 
    2. A step-by-step guide to using the "TryIt" feature can be found /wiki/spaces/APIArchive/pages/22675609.

 

Request a Client Credentials token via API

You can generate a token directly without using the web UI by using curl.  On the My Subscriptions page https://api-dev.ucsd.edu/store/site/pages/subscriptions.jag click the "CURL" button then select Client Credentials.  You should get a command like:

curl -d "grant_type=client_credentials" -H "Authorization: Basic VDdnbXRrVWdFaGlWRHo1djJlNTNKeEpSSnQ4YTpEVUpVN0dwNFNHOHhJa0ZHRF8zUzk4UUVDYmth, Content-Type: application/x-www-form-urlencoded" https://api-dev.ucsd.edu:8243/token

The element after Authorization: Basic is the Consumer Key and Consumer Secret separated by a :, base64 and url encoded. Invoking this command should get a new bearer token:

{"token_type":"Bearer","expires_in":2916,"access_token":"4130324514115d1a533baa4c1696283"}

Implicit Authentication to get Token

Another method for getting a token is to redirect the user to the Key Manager to authenticate with it.  The user will then be redirected back to your app with the token on the URL.  The use case here is that a user hits your application, when a token is needed the user is sent to authorize.  When your page is reloaded JavaScript can be used to retrieve the code from the URL and invoke the APIs via AJAX.

  1. Register your applications Callback URL (https://api-dev.ucsd.edu:9443/store/site/pages/applications.jag scroll to bottom, click edit on your application).  This is where the browser will be sent once the token is retrieved.  For testing it doesn't need to actually work, we can check the browsers info to verify the token is generated.
  2. Open a browser to http://api-dev.ucsd.edu:8280/authorize?response_type=code&client_id=T7gmtkUgEhiVDz5v2e53JxJRJt8a&scope=TEST&redirect_uri=http://localhost/myApp after replacing the ConsumerKey and the RedirectURI (with your callback url, they must match).
  3. Check the location that your browser was sent to, it should be something like: http://localhost/myApp?code=bd77892b4953c49376cbc31ed7d9c55

SAML2 Bearer Auth

Another way to request a token is to get the SAML Assertion that's sent from the SSO Server and pass it to the Key Manager.  The Key Manager is configured to trust the SSO Server so it will issue a Client Authentication token for the user mentioned in the SAML Assertion.

curl -X POST -k -u "4ppy0unf2TGPUyAbHgwBgM2Enfoa:nLmLl06rRHEgX0C9yxxD1rxyEUQa" 
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" 
-d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion={Base64 URL encoded Assertion}" https://localhost:9443/oauth2/token

For more information, refer to blog at http://soasecurity.org/2014/10/31/saml2-bearer-assertion-profile-for-oauth-2-0/

 

Please note: OAuth 2.0 specifies four separate authorization grant types: Authorization Code, Implicit Grant, Resource Owner, and Client Credentials. \The Authorization Code grant type is used in conjunction with authenticating users. The Client Credentials grant type, on the other hand, is used for service-to-service API calls which do not involve an authenticated user. The procedure of subscribing to and calling an API is different for each grant type.