Intro to REST APIs

Welcome to the Getting Started series!

What is an API?

An API (Application Programming Interface) enables one app to communicate with another. When developers of a system want to make its data and/or functionality available to external consumers — like their own mobile app, or apps that developers like you create — they’ll implement an API to enable this scenario. The API is the menu of operations that can be called to access data or functionality within the corresponding system.

For example, a system that has “users” may implement the following API operations for managing user data:

Add User – add a new user
Get User – get details about an existing user
Update User – update an existing user
Delete User – delete a user
List Users – get a list of all users

Given this API implementation, you could create an app that programmatically adds, gets, updates, deletes, or lists users in this other system.

**Yeah, but what is a “REST API”?**

There are several types of APIs, but by far the most commonly used one these days (and for the foreseeable future) is the REST API. REST stands for Representational State Transfer — an architectural pattern that defines certain principles for designing web services. A REST API (or RESTful API as it’s sometimes called) is simply an API that adheres to that design pattern.

But let’s not get hung up on technical jargon — the odds of anyone ever asking you to explain what “REST” means are slim to none! Just know this:

A REST API is just a type of API.
There are other types of APIs (e.g., SOAP APIs, RPC APIs, etc.) — but REST APIs are far and away the most common type of API in use these days.

How does an API work?

An API exists to receive requests, process data, and return responses. API requests and responses travel “over the wire” between client and server via HTTP(S). The Request | Response cycle works as follows:

Your app (i.e., your code) sends an HTTP(S) request to the API endpoint that corresponds to the desired operation.
The system that’s implemented the API receives and processes the request.
After processing the request, that system sends a response to your app indicating the outcome of the operation and often returning data as well.
Your app (i.e., your code) processes the API response and proceeds accordingly.

Why would I use an API?

You’ll most commonly use an API in the following scenarios:

The app you’re building needs to read, write, update, or delete data in another system.
The app you’re building needs to initiate an action in another system.

Use Case #1: The app you’re building needs to access data in another system.

Example: You’re building an app that lets users lookup a real-time price for the stock symbol they specify.

After a bit of online searching, you find an API that provides stock quote data — awesome!

In your app, you’ll build the UI (user interface) to collect the stock symbol that the user is interested in. When the user provides the stock symbol, your app will issue an HTTP(S) request to a stock quote API, requesting the real-time quote for that symbol. When the stock quote API returns a response, your app will read the response and display the real-time quote to the user.

API request | response example - stock price

Use Case #2: The app you’re building needs to initiate an action in another system.

Example: You’re building an app that requires new subscribers to electronically sign a contract.

Since your company uses DocuSign, you can use the DocuSign service to facilitate online signing of the contract in your app — perfect!

When a new subscriber registers in your app, you’ll collect their name and email address and issue an HTTP(S) request to the DocuSign API, requesting that the contract be presented to the specified person for electronic signature. When the subscriber signs the contract, your app saves a copy of the completed contract and redirects the user to members-only content within your app.