Intro to REST APIs

I know I got your hopes up, but we're not going to regurgitate what's already widely documented all over the place on the web. If you don't know what REST stands for, take 6 minutes and read this intro. Then continue on to learn what you can do in Skylight performance analytics with them.

If you're serious about using REST, you'll want to check out the following links as well:

• Postman - the best tool for the job
• Skylight analytics Public API documentation
• Querying Session PM data via API
• JSON Web Tokens and you!

Getting Started

Step 1 is to choose a tool - for the purposes of this Tutorial, I'll heavily recommend Postman. Without sounding too much like a salesperson for them, here are some of the reasons you should be using them:

• Class leading product
• 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 Skylight analytics instances
• Support for OpenAPI standards, making the import of our specs pretty easy

Step 1 - Download the tool

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

Step 2 - Import Skylight analytics API specifications

Let's get you access to our wonderful selection of REST APIs!

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

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

• Done!
  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 some global and environment specific variables

Some times you want to be able to re-use the same API in different environments - use global and environment specific variables to help you out there. Then you can imbed variables within the URL or REST payload using double curly brackets {{ variable_name }} .

• Find the environment settings cog in the top right corner

• Select the "Globals" option at the bottom of the manage environment page
• Add a global parameter called "protocol" and set the value to "https". Yes, all communication between Postman and Skylight analytics will be super secure!

• Add a new environment and add a "host" variable with the URL to your Skylight analytics tenant.

• Save and select your environment.

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

Step 5 - Get authenticated

Let's cover one more step before getting into some examples... authentication. We don't just let anyone issue APIs into Skylight analytics. You need to set up a session with Skylight analytics via a login request, where you'll get a token that Postman will magically send when you make other API requests. Just keep in mind that the token periodically expires, and you'll need to re-login and get a new one.

• Use the search to filter the Skylight analytics request collection to find the "Login" API

• Edit the URL to add {{protocol}} and {{host}} variables
• Check out the body of the API request, and you'll notice it asks for two additional variables - {{username}} and {{password}}. You can edit your environment variables to add them or just fill in the values here... you won't need them in any other API so don't really need to make them variables unless you have different credentials for different environments.

• Send it in!
• Check out 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

Try reseting someone's 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.

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

• Search for the particular user you need to reset - note their ID number
• 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.

• 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.

FYI - the onboarding URL is https:// {{host }}/ onboarding?token={{ onboarding token }}