REST API Basics

In this Learning Lab you will learn the basics of consuming a REST API, and how to use Postman to explore a REST API.

Objectives

Completion Time: 20 minutes

  • Understand the basics of consuming REST APIs
  • Learn how to use the Postman client to make API calls
  • Learn how to make calls to the Spark API

Prerequisites

In this lab, we are going to the Cisco Spark APIs and Postman to explore making API calls.

Background

  • If you are unfamiliar with Python and APIs or are new to programming, this is a great place to start! If you are a wizard of such things, feel free to move to the next module.
  • This lab will use Postman which is a web based tool to make the REST API calls. Postman allows engineers to easily discover the capabilities and syntax of a REST API allowing for an easier transition from API syntax to real code. If you do not already have Postman installed, you will need to install this tool.

Overview of APIs

We are going to begin our discussion on network programmability by discussing what an API is and why they are important. Let's start by making sure we have a good foundation by diving into some definitions.

An API (Application Programming Interface) is a way for two pieces of software to talk to each other. Think about the ways you typically interface with software. For example, you might open up a web interface to access your email. You might have a specific workflow to open up messages and file them away for later. Each of these workflows has a specific "interface" or way in which you achieve a certain task.

An API is similar in concept. Instead of humans interfacing with software, software interfaces with software. Rather than having a human point and click-through a workflow, an API exposes functionality to another application.

Why would you want to do this? One reason is that this allows for the development of rich applications with a wide variety of functionality. Let's go through an example.

Suppose you are the creator of a Restaurant Recommendation app and you want to easily integrate the ability to return a list of relevant restaurants in the area with a map application that displays where the restaurants are relative to your location. Would you create this functionality from scratch? Probably not.

Doing so would likely take you away from your core expertise. Also, think about all of the risk and learning curve required to build something like that from the ground up. Instead, it would be better to leverage a third party that already offers that functionality, and integrate the functionality into your applications.

A good example is a Maps Server. Rather than build map functionality from scratch, you could use an API provided the Maps Server to integrate map functionality quickly into your application.

The role of an API is to act like a contract that enforces a specification. Take a look at the image below.

Much like a wall outlet, an API enforces a specification of an interface. An API ensures that software adheres to the proper specifications much like an outlet ensures that devices adhere to the proper electrical specifications regardless of the vendor or device.

Step 1. Get Access To The Spark REST APIs

We are going to use the Spark REST API to start our programmability journey. Spark is a collaboration tool that allows people to chat and share files, plus other capabilities.

You need to set up a Spark developer account in order to explore the Spark REST API!

  1. Go to the Spark Developer website.
  2. Click on Sign Up button to create an account.
  3. Log in with your new credentials and click on the member icon located on the top right corner of the page and click on the 'Copy' button to copy your Access Token.



The token allows you to make Spark API calls.

Great! Now that we have the basics of APIs down, let's dive into REST APIs to see how they work.