In this course, you will be introduced to a web API architectural style called REST.
- Web APIs
- REST APIs
- REST API tools
- Software engineers
- Data engineers
- DevOps engineers
- Site reliability engineers
- Have at least a conceptual understanding of programming
- Be comfortable with data structures, data types, etc.
- A basic understanding of the HTTP protocol would be helpful but is not required
The REST architecture doesn’t specify implementation details such as which network protocol should be used. The architecture is more focused on how to build maintainable, scalable, and consistent web APIs. Having said that, it's worth noting that most implementations use HTTP. So, I’m going to use examples based on HTTP and URLs.
Let’s run through the six architectural constraints defined by REST. In order for an API to be considered RESTful it must use a client-server architecture. Having a server implement a standardized API allows different types of clients to communicate using the same API. The Client-server architecture allows server-side applications to evolve independently of client applications.
A RESTful API must be stateless. All requests must contain all information required for the server to complete the request. Being stateless means that the server doesn’t need to have any prior knowledge in order to process requests. All required data must be provided by the client when it makes a request. A RESTful API must be cacheable. Responses must be capable of specifying if a response object can be cached. Imagine if a user had to download a large static file each time a web page loads. Wasted bandwidth can add up quickly. This constraint ensures that the functionality exists to cache a response if it makes sense for the use case.
A RESTful API must use a single uniform interface for all resources inside a given API regardless of type. REST considers all resources to be equal. So they should all use the same interface for performing actions. Developers should be able to learn the interface and apply the same knowledge to all resources within the API.
A RESTful API should be layered. A layered approach to system design can provide multiple benefits. To name just two:
Layers can scale independently as needed.
This pairs especially well with the previous constraints of being:
Layers can also allow for service isolation.
This ensures that layers only need to know about other layers with which they directly communicate.
The final constraint for a RESTful API is code on demand. This constraint is an optional contextual constraint. Being able to automatically generate code capable of consuming the API on the client side is useful in certain use cases. For example mobile applications, video games client, command line interfaces, etc. Because code on-demand isn’t required for all use cases, this constraint is optional.
When first introduced many developers misunderstood the exact requirements of the REST architecture. Without software examples as guides developers picked and chose the aspects which worked for their application. In the years that followed many web APIs were erroneously labeled RESTful. It took years before REST was better understood. Even today, it’s difficult to point to real world examples which fully implement REST APIs as defined in the original thesis.
Many modern APIs follow the resource-based approach for abstracting data. Even if they omit some of the RESTful constraints. The original thesis is a rather detailed paper covering more than we can review in an introduction. I mention this so that when you find yourself using and interacting with APIs you don’t make assumptions about all REST APIs based on a specific instance of a “REST API.” Just know that the colloquial use of the term REST API is rather flexible.
Let’s visualize a basic REST API. This is similar to the web API from earlier, only more REST oriented. Recall that REST is resource-focused. Meaning that all data is represented as a resource. The resource in this example is the concept of a pet.
In the previous web API example there was a URL called locate-pets. Compare this to the REST example which uses the resource type in the URL. Notice rather than the API being named for its action it’s named for its resource. The resource in this case is a pet, though the plural form of the word is used as a common naming convention.
At this point, the difference between the two may seem fairly academic. After all, the web API version is basically the same as the REST version. The distinction is difficult to show until we begin to add more actions. Let’s expand our functionality. The web API defines actions as part of the URL. The REST API defines resources which can have actions performed.
REST APIs commonly follow HTTP semantics and use HTTP methods to represent specific actions for a given resource. The HTTP protocol is based on the notion of request and response. A request is sent to a server and a response is returned. A request includes an HTTP method which defines the desired action. Most REST APIs ascribe specific functionality to each request method.
GET requests are used to request one or a collection of resources.
POST requests are used to create a new resource
PUT requests are used to update a resource
PATCH requests are used to partially update a resource
DELETE requests are used to delete a resource
Notice the URL patterns for this example REST API. They start by specifying the resource and optionally specify a resource identifier. This is a pattern common to basic APIs for specifying resources and IDs using a URL. The request method determines the action taken and the URL specifies the resource and identifier.
The combination of being resource focused along with the other required constraints is what makes an API RESTful. The REST architecture doesn’t concern itself with implementation details such as HTTP methods, URL patterns etc. These are up to the API developers. However, REST does require the API interface to be internally consistent. Abiding to its own implementation choices.
Our example only included a single resource. Real-world APIs may include many different resources with differing connections to other resources. Collectively the resources which comprise the API are referred to as the API schema.
For schemas with interconnected resources the URL, patterns can become more complex. Notice in this example there are resources for orders and items. These two resources exist independently however they’re linked concepts since orders consist of items. The URL reflects the connection by allowing items from specific orders to be returned.
There’s no singular way to design and build APIs. It’ll depend on the use case. Some resources are highly connected and others are isolated. REST prefers to leave design choices such as API schemas and URL patterns up to API developers; as long as the API uses a uniform interface for accessing different resources
Alright, this seems like a natural stopping point. Here are some of the key takeaways for this content.
A web API refers to an API which is based on web protocols such as HTTP.
REST stands for representational state transfer.
REST is an API architectural style for building client-server applications.
It defines a means of communication and data representation.
REST introduces a generic means of representing data as resources.
RESTful APIs must implement at least the 5 required REST constraints.
RESTful APIs identify resources using a URI
Modern REST APIs are based on HTTP and its semantics.
Using HTTP methods to specify actions to take for resources.
Commonly REST APIs specify the resource name and identifier in the URL.
These patterns can become complex for highly linked resources.
An APIs schema defines the capabilities of the API by specifying resources and actions.
REST APIs can consist of many interconnected resources.
Alright, that's all for this lesson. Thanks so much for watching and I’ll see you in the next lesson.
Ben Lambert is a software engineer and was previously the lead author for DevOps and Microsoft Azure training content at Cloud Academy. His courses and learning paths covered Cloud Ecosystem technologies such as DC/OS, configuration management tools, and containers. As a software engineer, Ben’s experience includes building highly available web and mobile apps. When he’s not building software, he’s hiking, camping, or creating video games.