Intro to REST APIs

Getting Started

The first thing you need to do is choose a tool. For the purposes of this Tutorial, we recommend Postman. Recommendation is based on it's ability to:

• Share your APIs with a team of people via the shared workspaces
• Support for environment variables that let you quickly switch between tenants or Provider Connectivity Assurance analytics instances
• Support for OpenAPI standards, making the import of our specs pretty easy

If you need a quick refresher on REST, see: REST tutorial

For more information on APIs, see: Querying Session PM data via API

Step 1: Download Postman (or choosen tool)

• Go to https://www.postman.com/downloads/ and install the tool on your PC/Mac.

Step 2: Import Provider Connectivity Assurance analytics API Specifications

1. Go to http://api.accedian.io and download the Skylight analytics OpenAPI spec

2. Start Postman and choose to Import swagger.json file into Postman

You'll notice that there are three folders for APIs, v1, v2, v3. Try to stick with the later versions of APIs for unless you cannot find the corresponding one from later revisions.

Step 3: Setup Global and Environment Specific Variables

If you want to re-use the same API in different environments, use global and environment specific variables.

1. Embed variables within the URL or REST payload using double curly brackets {{ variable_name }} .

2. Find the environment settings cog in the top right corner, as shown below.

3. Select the "Globals" option at the bottom of the manage environment page.
4. Add a global parameter called "protocol" and set the value to "https". All communication between Postman and Skylight analytics will be secure.

5. Add a new environment and "host" variable with the URL to your tenant.

6. Save and select your environment.

7. Use the EYE icon to see your variables values at any time.

Step 4: Get Authenticated

Now you will need to set up a session with Provider Connectivity Assurance, via a login request, where you'll get a token that Postman (or your selected tool) will send when you make other API requests. Remember tokens periodically expires, and you may need to re-login and get a new one occasionally.

1. Use the search to filter the Provider Connectivity Assurance request collection and find the "Login" API.

2. Edit the URL to add {{protocol}} and {{host}} variables.
   Note: The body of the API request will ask for two additional variables - {{username}} and {{password}}.

3. (Optional) Edit your environment variables.
   You can add them or just fill in the values here.
   Note: You won't need them in any other API so you don't need to make them variables unless you have different credentials for different environments.

4. Send it in.
5. Validate the response and make sure received a successful response that includes: a 200 OK response code, relevant payload with details on your account, and authorization and cookie headers.

Examples

Reset User Password (admin only)

If you're an admin, you have the capability of looking for users to find their IDs and can issue a password reset API to get a new onboarding URL for them.

1. Find all users using the "Retrieve a list of Users known to Skylight AAA" API

2. Search for the particular user you need to reset, take note of their ID number
3. Using the Reset a password for a User provisioned in Skylight AAA, specify the {{userid}} in the URL or in the params as the number noted above.

4. Send that API, take the onboarding token from the returned payload and send it to the user so they can reset their password and resume their awesome work inside of Skylight analytics.

The onboarding URL is https:// {{host }}/ onboarding?token={{ onboarding token }}