REST APIs: Everything You Need to Know

Learn everything it takes to start working with a REST API and how they can help you build software faster and at a higher level of quality.

Ben Lloyd Pearson | August 4, 2020

Over the last two decades, REST has grown to be an extremely popular tool for building software applications to the point where it now includes a vast, rich ecosystem of developer tools. A survey from Rapid API determined that two-thirds of developers expect to increase their usage of REST APIs in 2020, and more than 80% of developers are either using REST in production, building a proof of concept with REST, or are investigating REST for a production service. 

REST is extremely versatile and can help to build software faster, more efficiently, and in a scalable manner. Here at Nylas, we work with REST APIs every day as we build out the email, calendar, and contacts APIs that are a part of the Nylas Platform. This article will cover everything you need to know start working with REST today.

Want a PDF of this article?

Share it with a friend or save it for later reading.

Table of Contents

Introduction to REST

REST is an acronym that stands for REpresentational State Transfer. First presented in a dissertation from Roy Fielding in 2000, it’s an architecture style ideal for designing loosely coupled applications that communicate over HTTP. It’s most often used in the development of web services and helps applications better leverage resources that are spread across multiple locations on the internet. A REST API is a service that allows you to access and manipulate data on a server via REST mechanisms.

Simply put, REST is a framework to organize interactions between diverse, independent software environments. 

The Principles of REST

At a high level, REST utilizes 6 architectural constraints which must be met for an interface to be referred to as a true REST API. They serve as the guiding principles of REST:

  • Client–server model: The client and server apps are independent of one another and are able to evolve separately without any inter-dependency. This makes REST APIs more flexible and scalable.
  • Uniform interface: Resources should behave consistently across the entire API, should have a single identifier to represent them, and should include all of the data that’s necessary to represent it fully while excluding unnecessary data. It also should follow clear naming conventions and link and data formats. 
  • Stateless: The server should treat every request as new, and never store anything about the most recent HTTP request. This means no session and no history.
  • Cacheable: Caching is a strategy to improve client-side performance and reduce server load. REST APIs must state whether data is cacheable or not.
  • Layered system: APIs, stored data, and authentication requests must be spread across different interfaces. This architecture helps enhance an application’s security by limiting components in each layer to interact only with the next immediate layer. 
  • Code on demand: This is an optional constraint and is used the least. It permits a client to download code from the API to be executed.

Resources: The Fundamental Building Block of REST APIs

Resources are the fundamental component of a REST API, and specific resources should be returned that match the location the client requested. Any piece of data can be a resource including documents, text files, images, services, collections of other resources, and more. The state of the resource at any particular time is known as resource representation, and this consists of data, metadata describing payload, and links that can help clients get additional related data. 

Unless explicitly documented otherwise, REST APIs return UTF-8 encoded JSON objects as the resource. This is designed to be easy for both humans and machines to create and consume. For example, The Nylas Platform provides most data in this format, here is an example of what it looks like for a resource that represents a user contact via the Nylas Contacts API:

{
    "given_name": "Stephanie",
    "surname": "Kwolek",
    "job_title": "Material Scientist",
    "company_name": "Fiber Synth",
    "birthday": "1923-07-31",
}

The Difference Between HTTP and REST

When learning about REST, it can be easy to get confused about the difference between HTTP and REST. While these are very closely intertwined, there are some distinct differences you should be aware of.

Hypertext Transfer Protocol (HTTP) is the life of the web. And while REST is not specifically restricted only to the web, it’s most commonly implemented as such. REST was inspired by HTTP and they both play to very similar strengths. However, without REST, you would need to build relatively complex conventions on top of HTTP for connection negotiation and data manipulation functions.

The design principles of REST underpin HTTP and allow you to build powerful interfaces that can be used from nearly any device or operating system. As a result, REST can be used wherever HTTP can.  But to be clear, REST and HTTP are not the same. Within the REST architectural style, data and functionality are considered resources and are accessed using URIs. These resources are acted upon by using a set of simple, well-defined REST operations. Alternatively, HTTP is the standard protocol that clients and servers use to exchange resource representations.

The Technical Advantages of REST

Now that we’ve introduced you to the primary concepts behind REST, let’s take a look at how REST can make your software better. The two major benefits of using REST are that it improves the portability of client apps by separating the user interface from the data and functionality that powers it, and it makes it easier for the different components of a product or service to evolve independently.

REST Decouples Client and Server Operations

REST scales very well because the client and server are very loosely coupled and the server is free to change the exposed resources at will. The client needs only know the initial URI, and the available methods. REST allows developers to more easily change the underlying servers, as long as they continue to send the expected data, allowing for rapid evolution of servers and for a large number of client apps to interact freely on an ad hoc basis. Other approaches can become untenable as the number of servers and clients grows.

REST Makes Interoperability Simpler

REST is the most widespread API standard for internet services. It has a flexible, provisional structure that is suited for an immense range of apps and services, and it’s easy to use and interact with because it helps you organize even the most complex applications into simple resources. REST APIs have native support in most programming languages, so you can integrate with them no matter the language your product is built in. 

When to Choose REST Over SOAP or GraphQL

REST isn’t the only option on the market for APIs, Simple Object Access Protocol (SOAP) and GraphQL are the two biggest competitors with the former being much older and the latter being much younger. While these all accomplish very similar tasks, they are fundamentally different items: SOAP is a protocol, REST is an architectural style, and GraphQL is a query language. However, this isn’t where the differences stop, let’s take a closer look at them.

SOAP

SOAP was introduced to the world in 1998, and is an extremely verbose protocol that requires the use of highly-structured XML for all requests. It’s ideal for situations where you need absolute data integrity for things like ACID compliance. However, with this reliability comes increased complexity because SOAP APIs require you to know the exact structure of the data you’re requesting before you interact with the API. This complexity also results in more bandwidth usage vs. REST APIs which can make SOAP untenable in situations where bandwidth is restricted or unreliable.

GraphQL

GraphQL is a query language Facebook released as open source in 2015. It solves problems REST sometimes has with over or under fetching data, particularly for use cases that involve complex sets of data that change frequently. It does this by allowing you to create queries that request both the data you want and the structure you want it to be presented in. While this makes it easier to represent complex data structures, the simplicity of REST means that it is much more efficient for situations with less complex data structure requirements. Read our guide on GraphQL to learn more.

How to Use a REST API

The next section of this article will explain everything you need to know to start using REST APIs. We’ll look at how to build REST requests and how to use cURL to interact with a REST API.

The Basic Components of a REST Request

There are two fundamental steps to making a request to a REST API:

  1. The client accesses a specific location on a REST API and states the method that should be executed, this is known as a request.
  2. The server executes the method, and returns data back to the client, this is known as a response.

There are four primary components that are a part of this process:

  • Endpoint: The location of a specific resource.
  • Headers: Meta information about the request or response that indicates things like authorization and the data type contained in the body.
  • Method: The type of interaction that is being executed on the resource. REST APIs can offer methods to create, read, update, and destroy resources.
  • Data (or Body): Contains the data payload that is either sent to or received from the server.

Now, let’s take a look at each of these components in greater detail.

Endpoints

REST APIs use Uniform Resource Identifiers (URIs) to create addresses for resources. The endpoint (or route) is the URI that’s requested; for REST APIs this is typically a URL, much like you would use in the web browser. For example, here is the URL for an endpoint on the Open Notify API that provides information about astronauts that are currently in space:

http://api.open-notify.org/astros.json

If you click that link, you should see a response in JSON format that lists data about these astronauts, at the time of this article there are three people on a historic trip to the International Space Station (ISS):

{
  "number": 3,
  "message": "success",
  "people": [
    {
      "craft": "ISS",
      "name": "Chris Cassidy"
    }, 
    {
      "craft": "ISS",
      "name": "Anatoly Ivanishin"
    }, 
    {
      "craft": "ISS",
      "name": "Ivan Vagner"
    }
  ]
}

Endpoints can also accept query parameters that modify the request to support additional functionality. To include query parameters, you need to add a question mark to the end of the resource URL followed by a list of key-value pairs. If you want to include multiple query parameters, you need to separate them with an ampersand. The next endpoint example accepts two query parameters to represent latitude and longitude, and returns timestamps for when ISS will pass over that point on the earth.

http://api.open-notify.org/iss-pass.json?lat=45&lon=180

Headers

Headers contain all of the metadata associated with the request, including information about the request and response body, authorization, caching information, and related cookies. There are numerous possible headers; here are some of the more common headers you’ll encounter while working with REST APs:

  • Content-Type: This indicates the media type that is contained in the response body and is used to inform the client about how to process it.
  • Authorization: This is included in the request, and it contains the credentials that are used to access a specific resource. Authorization methods will be covered in more detail later.
  • WWW-Authenticate: The server includes this in the response header when the client attempts to access a resource that requires authorization. This is often accompanied by a 401 unauthorized error, which is covered in detail later in this article.
  • Cache-Control: This allows both the client and server to define caching policies, which helps reduce latency and network traffic. However, the client can only set the caching policies to whatever the server supports, so this field is important for both requests and responses.

Methods

The method is the type of request the client sends to the server. The most commonly used REST methods are GET, POST, PUT, PATCH, and DELETE:

  • GET: Read a resource from a server. When a client performs a GET request, the server looks for the requested data and sends it back to the client if possible. This is the default request method.
  • POST: Create a new resource on a server. When a client performs a POST request, the server creates a new entry in the database and informs the client whether the creation was successful. 
  • PUT and PATCH: Update an existing resource on a server. When a client performs a PUT or PATCH request, the server updates an entry in the database and informs the client whether the update was successful.
  • DELETE: Delete a resource from a server. When a client performs a DELETE request, the server deletes an entry in the database and informs the client whether the deletion was successful.

Body

The body contains the data payload that is either sent to or received from the server. A REST body can contain virtually any media type, but the most commonly used media type is application/json. For example, here is what a resource that represents an email in a user’s inbox that’s connected to the Nylas Email API might look like: 

{
    "subject": "Learn about our latest line of Nuclear Ornithopters!",
    "body": "Let's setup a meeting to talk about the new models we have in stock!",
    "unread": true,
    "date": 1557950729,
    "from": [
        {
            "email": "[email protected]",
            "name": "Leonardo Da Vinci"
        }
    ],
    "to": [
        {
            "email": "[email protected]",
            "name": "Marie Curie"
        }
    ],
}

How to Authenticate to REST APIs

Authentication is a critical component of internet security, and any REST API that lets clients access or modify sensitive or critical data must have an authentication system in place. If you want to integrate with a REST API, you will need to account for this. There are two major methods for authentication: username and password, otherwise known as basic authentication, or OAuth, which lets you authenticate with an access token that represents an authorized account.

REST APIs can support either of these methods of authentication, but OAuth is by far the preferred method because it offers much better security than basic authentication. With basic authentication, access is typically binary, i.e. either you can access all account data and functionality or none of it, and access can typically only be revoked by changing the user’s password. With OAuth, access tokens often represent both an authorized account and a set of scopes that provide access only to specified data and functionality. This makes it much easier to grant and revoke access to the resources a REST client needs.

The current standard is the OAuth 2.0 framework, which enables a third-party application to obtain limited access to an HTTP service on behalf of a resource owner. It does this by orchestrating an authentication between the resource owner and the HTTP service.  Once this has been completed, the REST client can use the access token in a bearer authentication header; this type of authentication should only be done over HTTPS (SSL).

The next section will go into more details about how REST authentication works when using cURL.

How To Test REST APIs With cURL

You can quickly test how your REST API is functioning from the command line using cURL. cURL is a lightweight tool for making HTTP requests without a web browser. With it, you can make GET, POST, PUT, PATCH and DELETE requests to a REST API by passing the -X option followed by the desired command. This section will show you examples of how to do this.

Use GET to Request Data

In the terminal, we’ll use cURL to make a GET request to the Open Notify API. This is a simple, yet nifty API that has information about astronauts that are currently in space:

curl -X GET "http://api.open-notify.org/astros.json"

You should see a response in JSON format that lists data about these astronauts, at the time of this article there are three people on a historic trip to the International Space Station:

{
  "number": 3,
  "message": "success",
  "people": [
    {
      "craft": "ISS",
      "name": "Chris Cassidy"
    }, 
    {
      "craft": "ISS",
      "name": "Anatoly Ivanishin"
    }, 
    {
      "craft": "ISS",
      "name": "Ivan Vagner"
    }
  ]
}

How to Authenticate to a REST API With cURL

Most REST APIs that allow clients to modify data require some form of authentication, so before we look at the other methods, we first need to find out how to authenticate with cURL. The next examples will demonstrate functionality for an account connected to the Nylas Platform. If you want to successfully execute the commands yourself, you will need to get your own API keys, but you can use the conventions shown here for any other REST API you want to interact with.

If the REST API you’re working with allows you to use basic authentication, you can do so with cURL by using the -u option, followed by the username and password separated by a colon.

curl -u "username:password" "https://api.nylas.com/account"

If you want to use an access token to connect to a REST API, you need to pass it as a bearer token in the request header using the -H option:

curl -H "Authorization: Bearer m7piDJm9tidvsdfgsdgCWhBTb2UV18" "https://api.nylas.com/account"

Use POST to Create Data

Now, we’ll use the Nylas Calendar API to demonstrate how to create new data on a REST API with POST. Nylas offers an Events endpoint that accepts a data payload that represents a calendar event, containing information like the time, description, title, and list of participants. In the next example, we will include a JSON representation of an event in the data payload of the cURL request with the -d argument. This endpoint requires authorization because it allows you to modify user data, so it includes the bearer token in the Authorization header.

curl -X POST 'https://api.nylas.com/events' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
      "title":"National Inventors Day!",
      "calendar_id": "jfhd83eh392ksks9",
      "participants": [
          {
              "name": "Thomas Alva Edison",
              "email": "[email protected]"
          }
      ], 
      "description": "Celebrate the work of historical inventors.",
      "when": { "date": "2021-02-11" }
     }'

Take note of the calendar_id in the example above, it represents the ID of the calendar we want to add the event to. In the case of Nylas, this value references a separate Calendar resource that can also be accessed via the Nylas REST APIs. 

Use PUT and PATCH to Modify Data

To modify existing data via a REST API, you often need to start with some sort of reference for a resource that already exists. REST APIs typically assign unique IDs or URIs for each individual resource. For example, the Nylas Calendar API will automatically assign a unique id for all events. Then, when you want to make a modification, include this ID in the requested URI. 

PUT replaces a resource entirely, even if you only change a single element of many, so you need to provide all data you want the resource to have. The next example shows what it would look like to add an additional participant to the event we created earlier. Take note of the unique event ID at the end of the URI and the modification to the participants attribute.

curl -X PUT 'https://api.nylas.com/events/js93j02jb0spzbmaj5' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d '{
      "title":"National Inventors Day!",
      "calendar_id": "jfhd83eh392ksks9",
      "participants": [
          {
              "name": "Thomas Alva Edison",
              "email": "[email protected]"
          },
          {
              "name": "Dorothy Vaughan",
              "email": "[email protected]"
          },
      ], 
      "description": "Celebrate the work of historical inventors.",
      "when": { "date": "2021-02-11" }
     }'

PATCH, on the other hand, updates only the data that is included in the request body. It functions in the exact same manner as PUT, but the data payload only needs to include the data you want to change. In the example above, we could have simply passed only the participants attribute to the resource URI. 

Use DELETE to Remove Data

To delete data from a REST API, you also need to reference an existing resource and pass the DELETE command to the -X argument, like so:

curl -X DELETE 'https://api.nylas.com/events/{id}' \
  -H 'Authorization: Bearer ACCESS_TOKEN'

How to Check HTTP Status Codes and Handle Errors

All REST requests return a status code as part of the HTTP response that informs the client of the request result. HTTP defines numerous standard status codes that are shown as a subset of numerical codes, ranging from 100 to 599 depending on the type of status that is conveyed. If you’re using cURL to make a request, you can pass the -I option to return the status code to the terminal. In this section, we’ll show you how to identify a successful REST API request and deal with some of the more common errors that might occur while working with one.

200 – OK

This indicates that the REST API successfully carried the requested action and that no more action is necessary. A 200 response should also include a response body that is dependent on the method used in the request. For example, GET will return an entity that corresponds to the requested resource, and POST will return an entity that describes or contains the result of an action.

4xx – Client-Side Errors

The 400-499 code range, indicates problems on the client side, i.e. the request the client made isn’t valid. Let’s take a look at some of the more common client side errors you might encounter while working with REST APIs.

400 – Bad Request

400 is the generic client-side error status that can be the result of a range of problems including malformed request syntax, invalid request message parameters, and incorrect request routing. When this error occurs, the client should make modifications to the request before sending it to the REST API again.

401 – Unauthorized

A 401 error code indicates that the client didn’t have sufficient privileges to operate on the requested resource.This is typically the result of inaccurate or nonexistent access credentials. The client should modify the request to include suitable authentication information in the request.

403 – Forbidden

A 403 error response indicates that the client’s request is formed correctly, but the REST API refuses to honor it. This is typically the result of the client not having the necessary permissions for the resource. This differs from a 401 error because it means the client is authenticated, but isn’t allowed to access the requested resource with the provided method.

404 – Not Found

The 404 error status code indicates that the REST API can’t map the client’s URI to a resource. In other words, the API can’t find the requested resource. No indication is given as to whether the condition is temporary or permanent and subsequent client requests can be permissible because the resource might become available. This status code is commonly used when the server does not wish to reveal exactly why the request has been refused, or when no other response is applicable. 

If you encounter this error, you should verify the request to ensure it is for a valid resource. You can also try again later in situations where there might be a delay before resources are made available.

405 – Method Not Allowed

405 errors indicate that the client tried to use an HTTP method that the resource does not allow. For instance, a read-only resource might only support GET, so requests to PUT, POST, or DELETE would return this error. If you encounter this error, modify your request to a method the resource allows.

429 – Too Many Requests

A 429 error occurs when a client attempts too many requests within a certain timeframe. This error is triggered based on rate limit settings the REST API service provider has set, and this is used to prevent their servers from being overloaded. To avoid this issue, you should make yourself aware of any rate limit issues the API might have and find ways to optimize queries to reduce the number of requests you need to make.

500- Internal Server Error

Most REST APIs use 500 status codes whenever the request handler raises an exception. This represents a problem with the REST API server and it’s possible that simply retrying the request can resolve this problem. If the problem persists, you should contact the REST API provider to further diagnose the issue.

How To Build a Secure REST Integration

Security is an integral part of any development project, especially for REST APIs. Here is a checklist of items that will help you build a secure REST API integration:

  • Keep it Simple: Keep your requests simple and efficient. Every time you make the solution unnecessarily complex you create potential vulnerabilities.
  • Use HTTPS Wherever Possible: HTTPS is easy to use and offers many important security benefits. Specifically, you should never send access credentials or sensitive data over an unsecured HTTP connection.
  • Hash Credentials When Storing Them: Passwords and OAuth credentials must always be hashed to protect them from exposure, particularly in the event of unauthorized access to your systems. If you need to store access credentials for future use, you should always use a hashing algorithm like PBKDF2, bcrypt and scrypt for increased security.
  • Never Expose Sensitive Information in a URL: Usernames, passwords, session tokens, and API keys should not appear in the URL because this makes it possible to capture them in web server logs, and thus, easier for a malicious actor to exploit them.
  • Use OAuth: Basic authentication is fine for testing a REST API, but you should always use OAuth whenever it’s available because it provides better control over access to data and functionality in a REST API.

Start Building With REST Today

Twitter, Google, Facebook, and Microsoft are among the hundreds of companies that have adopted REST APIs for their products because they are an ideal mechanism to put their functionality and data in the hands of developers everywhere. Maybe your aspirations reach that high, or maybe you simply want to improve the efficiency of your internal development teams.

Either way, REST is a battle tested framework for building scalable, efficient, and highly functional interfaces for software development. If you’re building an app, chances are you should be building at least part of it with REST. With the knowledge in this guide, rest assured that you’re now armed with all the knowledge you need to start building with REST today.

Ben Lloyd Pearson

Ben is the Developer Advocate for Nylas. He is a triathlete, musician, avid gamer, and loves to seek out the best breakfast tacos in Austin, Texas.