Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Productivity
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why NylasREST 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.
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.
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.
Table of Contents
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.
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:
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",
}
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.
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 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 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.
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 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 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.
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.
There are two fundamental steps to making a request to a REST API:
There are four primary components that are a part of this process:
Now, let’s take a look at each of these components in greater detail.
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 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:
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:
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": "leo@ornitech.com",
"name": "Leonardo Da Vinci"
}
],
"to": [
{
"email": "marie@radioactivity.com",
"name": "Marie Curie"
}
],
}
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.
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.
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"
}
]
}
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"
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": "tom@brightideas.com"
}
],
"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.
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": "tom@brightideas.com"
},
{
"name": "Dorothy Vaughan",
"email": "dorothy@spacetech.com"
},
],
"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.
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'
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.
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.
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 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.
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.
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.
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 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.
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.
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.
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:
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.
Please enter your email address and receive the latest updates.
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.
