Salma Alam-NaylorIf you’ve had a look at the Contentful docs, you’ll have seen the acronyms REST and API in at least a few places! But what does it all mean? Let’s break it down.
What is an API?
API stands for Application Programming Interface, which is a way to communicate between different software services. Different types of APIs are used in programming hardware and software, including operating system APIs, remote APIs and web APIs — like the APIs that Contentful provides. If you’re new to development, I recommend you check out this blog post — What is an API? to get a good grounding on APIs and HTTP, in order to prepare for what we’re going to cover in this post.
Now that you’ve got up to speed on APIs and HTTP, how does REST fit into it? Let’s take a look.
What does REST mean?
REST is an acronym for Representational State Transfer, which is a term introduced in 2000 by American computer scientist Roy Fielding in his dissertation “Architectural Styles and the Design of Network-based Software Architectures.” REST is a set of rules and guidelines for creating resource-based web services that are stateless (we’ll unpack this later).
You might hear REST APIs described as RESTful, or following a RESTful architecture.
Rules of Representational State Transfer
Let’s take a look at some of the most important concepts of a RESTful API. This list is not exhaustive but is designed to give an overview of how REST architecture is designed. Not all APIs are RESTful APIs — and some APIs take inspiration from the principles of REST without following the rules completely.
RESTful APIs have a predefined set of operations available to a user
Developers and documentation often talk about “functionality being exposed via an API.” APIs usually do not allow for complete control over back-end systems. Instead, predefined functionality and operations are made available to users of APIs. Good APIs come with great documentation that describes how to send data in the correct format and what data to expect from each piece of API functionality.
New features are often added to APIs using a versioning system to ensure that large-scale applications are protected from potential breaking changes. As a result, you may end up working with differently versioned API URLs in your applications. For example, you might see https://myawesomeapi.dev/api/v1/users vs https://myawesomeapi.dev/api/v2/users in the wild. Notice the difference between the URLs — /v1 vs /v2.
RESTful APIs are based on resources
Responses from RESTful API calls over HTTP — usually called payloads — are returned as HTML, XML, JSON or similar text-based representations of resources that exist as stored objects. A stored object — or resource — can be anything, such as a blog post stored in a document database, a URL to a hosted image, or data about a user stored across multiple tables in a relational database.
The format of the URLs for RESTful API endpoints are descriptive and self-documenting. Each URL — requesting a resource or requesting to modify a resource — describes what type of resource is being requested from the API.
For example, here’s a Contentful Content Delivery API (CDA) URL that requests information about a single Contentful space via an HTTP GET request. A Contentful space is like a bucket for your Contentful content, which has a name and unique ID.
Notice the /spaces part of the URL — which defines that the resource we’re asking for is data that represents a space.
https://cdn.contentful.com/spaces/{space_id}?access_token={access_token}
The URL requires two dynamic URL parameters — space_id and access_token. The space_id is the unique identifier of the space we’d like to get information about from the database, and the access_token is for authentication (more on this later when we talk about how REST APIs are stateless).
Here’s a second example from the Contentful Content Management API (CMA), this time asking for a specified environment resource available inside a space via an HTTP GET request (see /environments in the URL). Contentful spaces allow for multiple environments in order to manage content and feature migrations in your applications. This API endpoint takes two dynamic URL parameters — space_id and environment_id, and requires an authentication token to be sent via an HTTP Authorization header.
https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
RESTful APIs allow resources to be read or modified
In the examples above, we used HTTP GET requests to read information about a Contentful space from the CDA and read information about an environment inside a space from the CMA. In addition to retrieving information about stored resources, RESTful APIs also allow you to create, update or delete resources in separate API calls.
Using the CMA, we can also create, update or delete resources using HTTP POST, PUT and DELETE methods. What’s great about this, is that not only do RESTful API URLs describe the resources concerned in the format of the API URLs, they also describe the action you’re performing on the API according to the HTTP method implemented.
You may have heard of the acronym CRUD when referring to RESTful API architecture. CRUD stands for Create, Read, Update, Delete — which are the standard actions available on RESTful APIs over HTTP.
Now we know how to read from the Contentful APIs, let’s take a look at how we can create, update and delete.
Creating a new environment with HTTP POST
Use HTTP POST to create a new environment with the CMA.
Send a POST request to the following URL:
https://api.contentful.com/spaces/{space_id}/environments
With the following HTTP headers:
Authorization: Bearer <cma_token>
"Content-Type": application/vnd.contentful.management.v1+json
And the name of the environment you wish to create in the body of the request:
body: {
"name": "My new environment name"
}
An HTTP POST request to this API URL creates a new environment with an auto-generated ID. While it’s perfectly fine to create an environment with an auto-generated ID, we recommend creating environments with a specified ID to have more control in your automation scripts. And the good news is, you can do this with an HTTP PUT request.
Creating or updating an environment with HTTP PUT
I like to think of the HTTP PUT method as literally putting more specific information into the data store, rather than sending off a request via POST for the API to create something for me.
To create a new environment with a specified ID, send an HTTP PUT request to the following URL, where {environment_id} is the ID you wish to specify.
https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
Use the following HTTP headers:
Authorization: Bearer <cma_token>
"Content-Type": application/vnd.contentful.management.v1+json
And send the name of the environment you wish to create in the body of the request:
body: {
"name": "My new environment name"
}
To update an environment, make the same API call as above, but with an additional HTTP header, specifying the last version of the environment you are updating, like so:
X-Contentful-Version: <existing_version>
Deleting an environment with HTTP DELETE
To delete a particular environment within a space, send an HTTP DELETE request to the following URL, where {environment_id} is the ID of the environment you wish to delete:
https://api.contentful.com/spaces/{space_id}/environments/{enviroment_id}
And use the following HTTP header:
Authorization: Bearer <cma_token>
Now, here’s the fun bit!
Notice how the API URLs to create with a specified ID, read, update and delete an environment are all exactly the same!
RESTful API calls are performed on a single URL representing the type of resource you wish to create or modify. The difference is that the read method uses an HTTP GET request, the create and update method uses HTTP PUT (with different HTTP headers depending on the action you want to perform), and the delete method uses HTTP DELETE.
This is where RESTful architecture really shines. The combination of the HTTP methods coupled with the resource-based URLs and different HTTP headers makes navigating and working with RESTful APIs pretty intuitive and very well structured.
Click here to see the CMA environments documentation referenced above in full.
RESTful APIs are stateless
Stateless in this context means no information is passed between different interactions or API calls. In stateless architecture, each request to an API must be processed based only on the information sent with the request at the time. For example, if you make a call to the API with an authentication token, the API won’t remember that you’re authenticated in additional requests. If you wish to make more calls to the same API, you must send an authentication token in all subsequent requests.
You’ll notice that in each API request above to the CMA, an authorization header was included with each request. Similarly, in the first GET request from the CDA, the authentication token was passed as a URL parameter.
In summary
An API is a way to communicate between different software services using code. REST is a set of rules and guidelines for creating a particular type of API, and not all APIs are RESTful APIs.
REST stands for Representation State Transfer. RESTful APIs:
- Have a predefined set of operations available to a user
- Are based on resources
- Usually allow CRUD operations on resources — and CRUD stands for Create, Read, Update, Delete
- Are stateless
Explore the Contentful documentation to solidify your understanding and if you’ve got any questions, find me on Twitter.
