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
There are many ways to build web APIs using many different cross-industry technologies. This course focused on a specific type of web API called: REST APIs. REST was introduced as an architectural style of creating maintainable long-term web APIs. It establishes a specific way of structuring APIs which focuses on a generic data representation referred to as resources.
Resources can represent data based on the data’s type. Knowing the resource type allows clients to display resources independently. For example images, HTML, text, videos, etc are all different types of resources which are rendered differently.
Resources are identified by a uniform resource identifier also known as a URI. A URL is a specific type of URI and commonly used as a URI for REST APIs. REST generally doesn’t specify requirements for specific implementation details such as network protocol, API schema, etc. However, most modern REST APIs are based on HTTP and or HTTPS.
REST promotes using a standard interface for interacting with resources. This is commonly done using HTTP methods and URLs. Many REST or REST-inspired APIs use HTTP methods to determine which action to take for a given resource. Here’s a mapping of commonly used HTTP methods and their expected actions. Notice that each HTTP method performs specific actions on specific resources. Note that this isn’t an exhaustive list of HTTP methods. Though, these are among the most common.
REST APIs commonly specify both the resource type and resource identifier in a URL path. This is found across many different web APIs. Interconnected resources might use more complex patterns which specify linked resources as more of a series of request type - request identifier pairs.
API designers and developers are responsible for determining an API's schema. The schema defines all of the available resources and actions. Schemas are often represented in formats JSON and YAML. These formats are sometimes created in code and sometimes created by humans for the purpose of auto-generating API code.
For an API to be considered RESTful it must adhere to the REST architectural style. Which defines some application constraints. In order to be considered a RESTful API, the API must:
Use a client-server architecture
Use a uniform interface
The API can:
Implement code on-demand
These constraints in addition to the resource focused approach allow REST APIs to become more maintainable for long-term applications. Long-term applications have to consider the impact of changes. API changes can break client functionality if not done carefully. This introduces needs such as API version control, among others. REST as defined in the original thesis describes a system which understands how to perform actions on interconnected resources. Resources define links to other resources which clients can navigate in a manual or automated manner. These links inform the client of all available actions for given resources.
I think it might be difficult to point to a real-world example which lives up to the system as originally described. Most APIs labeled as a REST API may not strictly adhere to the original design. That said, many of the aspects of REST are independently useful. As you begin to explore REST APIs further make sure to consider the fluid nature of the term REST API in the real world.
There are different tools in the web API ecosystem. Curl, Postman, RAML, OpenAPI, and the list goes on. Creating APIs intended for long-term use have specific needs. REST was introduced to address those needs in a very generalized manner. REST isn’t the only style of web API. In many use cases, REST would be considered over engineering. Which is likely why so many web APIs selectively follow some of the aspects of REST.
If you're interested in building web APIs, search for web API libraries in your preferred language. Get some practice understanding how to map resources and actions to code. Each library provides different mechanisms. Practice sending requests and receiving responses. If you’re not already familiar with the HTTP protocol I recommend the subject as future research. Web APIs are commonly built on top of HTTP. Making it worth understanding.
If you’re interested in designing web APIs I recommend doing further research into OpenAPI, RAML, and any other generic definition mechanisms. Knowing how to define an API schema in a generic manner will allow developers to consume the schema. Okay, this seems like a natural stopping point. I hope this course has been helpful in introducing you to REST APIs. Thank you so much for watching and I’ll see you in another course.
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.