Digital Media Concepts/REST API

Introduction

REST, short for REpresentational State Transfer, is an architectural framework for managing the exchange of information on hypermedia distributed systems. Proposed by Dr. Ray Fielding in his 2000 dissertation, REST outlines a set of rules and conventions for building and interacting with web services and managing client-server communication using the HTTP model.

Design principles

Uniform interface

The uniform interface simplifies and decouples the architecture, allowing for independent development of the client and the server. REST is defined by four interface constraints:

Identification of resources

Any information that can be named is a resource, such as a document or image. In other words, any concept that might be the target of an author's hypertext reference qualities as a resource. Resources should be unique and identifiable through a single URI. The URI should not change across interactions and when the state of the resource changes. If the resource has been relocated, the server should communicate to the client the code particular to the request failure (~300) and give the client a link to the new location of the resource.^[3]

Manipulation of resources through representations

Information about a request or response can be summarized in a data format specified by the client to the server. Common forms of resource representation are JSON, XML and HTML.

Self-descriptive messages

Each message includes enough information to describe how to process the message, such as the format chosen for resource representation.

Hypermedia as the engine of application state (HATEOAS)

This constraint allows the client to navigate a service dynamically through hypermedia links provided in responses, instead of hard-coded URLs or endpoints. This enables greater flexibility and decouples clients from server-side changes, making the system more adaptable and scalable without breaking existing clients.

Separation of concerns

The client and server components should differentiate themselves in the tasks they concern themselves with. The client takes care of UI and request-gathering, while the server focuses on data access, workload management, and security. Constraining each component to their specialized concerns makes the client more scalable and less strict on which platform it is ported to.^[1]

Statelessness

Each request to the server must contain all the information necessary for the server to understand and fulfill the request. Session information is kept entirely on the client and away from the server. Statelessness improves a service's visibility (the server need not look beyond a single request to fully understand it), reliability (which eases the task of recovering from partial failures), and scalability (not having to store state between requests allows the server to quickly free resources).^[2]

Cacheability

Every response sent back to the client must specify whether it is cacheable or non-cacheable. If the former, the client has the right to reuse the data for subsequent requests.

Layered system architecture

The layered architecture allows a system to be composed of hierarchal layers by preventing a component from seeing beyond the immediate layer they currently interact with.

Benefits

Scalability

Separation of the client and the server allows development teams to scale the product without much difficulty.

Flexibility and portability

Because REST APIs require data to be correctly formatted in requests, migrating from one server to another is feasible. Additionally, database changes can be implemented at any time.

Independence

The client-server separation enables different aspects of a project to develop independently. REST APIs can also adapt to various syntax and platforms, enabling testing several environments at a time during development.

Lightweight

REST APIs are efficient and quick, leveraging the HTTP standard, which accommodates various formats like JSON, XML, and HTML. This makes them well-suited for mobile applications, IoT devices, etc.

Challenges

REST endpoint consensus

While the format of URLs can vary, maintaining consistency throughout your API is essential. Unfortunately, as operations become more complex, the number of possible combinations increases, making it challenging to ensure consistency, especially in large codebases with many developers.

REST API versioning

API versioning involves creating multiple versions of an API to accommodate changes without disrupting users. To avoid compatibility problems, APIs are often versioned, but this means older endpoints remain active, which can lead to increased workload as multiple versions must be maintained.

REST API authentication

Authentication methods for APIs can differ based on their context. Some third-party applications are treated as logged-in users with specific rights, while others allow registered users to access only their data, such as emails or documents. This great variety among authorization approaches potentially complicates the process and hinders the progress toward building the first API.

REST API security

While RESTful APIs simplify access and manipulation of applications, security issues can still arise. For instance, a client might send numerous requests per second, overwhelming the server. Other security challenges include:

• Lack of proper authentication
• Lack of rate limiting and throttling
• Failure to encrypt payload data
• Incorrect HTTPS implementation
• Weak API keys that can be easily compromised

Multiple requests and unnecessary data

A response may contain more data than needed or require additional requests to access all relevant information.

References

^[1][2] "Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)". ics.uci.edu. Retrieved 2024-10-23.

^[3] "What RESTful actually means". codewords.recurse.com. Retrieved 2024-10-23.

What Is a REST API? Examples, Uses & Challenges | Postman Blog. b. blog.postman.com. Retrieved 2024-10-23.