Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

Postman is a free Chrome extension that is designed to assist in making web service calls.  It's an excellent tool for testing your backend API, either directly or through the API Manager.

This page will document how to invoke a web service thats being protected by the API Manager.

API Manager Overview

Here is a short version of the steps required to invoke an API through the API Manager.  These steps do not cover making / registering the API, they assume you are invoking an API that's already in the API Store.

  1. Register your Application (Do only once, Optional)
    1. If you haven't already, register your application by going to the "My Applications" tab of the api store.  Alternatively you can use the "DefaultApplication" that was made for your account.
  2. Subscribe your Application to the API (Do only once per application & API)
    1. Go to the store, find the API, select your Application from the drop down box and press subscribe.
  3. Get a Access Token by authenticating (Do once per session, tokens are good for an hour)
    1. One way to get a token is to go to the "My Subscriptions" tab of the API Store, selecting your Application and pressing "Re-Generate".  A fresh token will be made and shown in the "Access Token" section of the page.
    2. The alternative way is to invoke a web service on the API Manager.  The Getting an Access Token section of this page covers how to do with with Postman.
  4. Invoke the webservice on the API Manager
    1. The token retrieved in Step 3 will be included as a head on the web service request.

Getting an Access Token

One of the major features of the API Manager is security.  So before you invoke an API you have to authenticate with the API manager.  There are several different ways to do this and they are covered the page about OAuth Grant Types.  For this example we will be using Client Credentials grant type because it's one of the easiest to do in this kind of setup.  

Client Credentials Grant Type

For testing Client Credentials is easier because a user doesn't have to log in and it should be sufficient in most cases.  Because no user is logging in, user data such as PID won't be available to the back end service which will cause problems if the API relies on that data.  For those situations see the alternative method of getting a token below.

1. Get the Client Key and Client Secret for your application by going to "My Subscriptions" on the API Manager Store.  These Client Key and Secret will be hard coded into the client applications, so we must add them into Postman.  They don't change but are different for each application.

To be used in a HTTP request we must join the Client Key and Secret with a ":" and then Base64 encode them.  Fortunetaly the API Manger does this for us when it gernerates the cURL examples, so click the cUrl button and select Client Credentials.  The resultant command will have then encoded string ready for use.

2. Open Postman and click "Reset this Tab" to clear any previous settings

3. Enter the following details

  • Make the request a POST.
  • The URL of the API Manager's token web service: https://api-qa.ucsd.edu:8243/token
  • Add a header with the encoded Client Key and Secret
    • name: "Authorization"
    • value: "Basic <<encoded Client Key and Secret from above>>" for example "Basic YV9zSDBCdzEya2NuZkZFSmpKZkNmeW55TGdrYTowQXhmeGVVdDc4SksyMl9Yd3lDOFBOSDR5OUlh"
  • Set the Body to be "x-www-form-urlencoded"
  • Add a body key/value saying we are doing Client Credentials grant type
    • name: grant_type
    • value: client_credentials
  • Press Send

4. Save the request by pressing the green disk icon. 

Now each time you open postman to invoke your APIs, first run this request to get an Access Token.  Access Tokens are only valid for an hour.  If there is already an active token with some time left before it expires, the API Manager may return that one.  The next steps will show how to use this token to invoke an API.

 

Invoking an API

The last section covered invoking the token API to get an Access Token, invoking any other API is very similar.  This section will cover how to invoke the WeaterAPI in the API Store.

1. Find the API you want to invoke on the API Store (https://api-qa.ucsd.edu/store for QA & Dev, https://api.ucsd.edu/store for PROD).

2. Read the Documentation and the "API Console" tab to work out the URL to call.  Specifically you need:

  • the URL of the service
  • the resource you want to use
  • any required parameters or extra URL content.

Depending on the level of documentation this may require contacting the API implementor.  For APIs in the QA API Store, this is almost always the case.

1. Create a empty Postman request (see step 2. in Invoking APIs with Postman above)

2. Enter the following details:

 

  • No labels