Page History

It is simply impossible to adequately describe REST in this document. There will be some effort in this article to offer some understanding because it is the key reason for developing the SRP HTTP Framework in the first place.

In short, REST is an architectural style, or approach, of communications between different computer systems. While the theory of REST lends itself to any computing system, it was given birth and lives primarily in the web.REST  REST is arguably a formalized explanation of the way the internet (via HTTP) is meant to be used. REST offers a set of constraints that guide how the communications are to be properly handled. These constraints aim to build systems to achieve with greater visibility, reliability, and scalability. A full implementation of the REST architecture extends beyond APIs, but APIs are where REST principles are most actively used.

It is helpful to understand REST APIs by first looking at an alternative API style that is more familiar to us: Remote Procedural Call (RPC). RPC APIs treat the server primarily as an engine to execute procedures, and these procedures are named either in the URL (e.g., typical CGI) or in the payload (e.g., SOAP). RPCs leverage HTTP as a transport mechanism, while generally not giving much attention to the broader design and features that HTTP provides. Consider APIs that are needed to provide full management of system users. In an RPC approach, this would likely require at least four unique APIs (or URLs):

• GET /GetUsers (Retrieves a list of all users from the server.)
• GET /GetUsers?UserID=GeorgeWashington (Retrieves the user with an ID of GeorgeWashington from the server.)
• POST /CreateUser (Assuming there is a payload with user information, this will create a new user on the server.)
• POST /UpdateUser (Assuming there is a payload with updates user information, this will update the user on the server with only the information provided.)
• GET (or POST) /DeleteUser?UserID=GeorgeWashington (Deletes the user with an ID of GeorgeWashington from the server.)

Note that the emphasis is on the URL rather than the HTTP method. The only reason POST must be used in two of the APIs is because GET normally cannot send payload content. The main point is that there are four different APIs (GetUser, CreateUser, UpdateUser, DeleteUser) that have to be documented and supported by the client. REST APIs treat the server as a destination where resources are accessed. While the server may indeed be executing procedures, this is obscured from the URL itself, allowing the user to think about the resource as an item rather than an action. REST APIs rely upon the HTTP method (GET, POST, PUT, DELETE, etc.) to determine what should happen to that resource. Hence, through the use of these HTTP methods, a single URL can take on several meanings. This simplifies API design and the need for extensive documentation, as seen below:

• GET /Users (Retrieves a list of all users from the server.)
• GET /Users/GeorgeWashington (Retrieves the user with an ID of GeorgeWashington from the server.)
• POST /Users (Assuming there is a payload with user information, this will create a new user on the server.)
• PUT /Users/GeorgeWashington (Assuming there is a payload with updates user information, this will update the user with an ID of GeorgeWashington on the server with only the information provided.)
• DELETE /Users/GeorgeWashington (Deletes the user with an ID of GeorgeWashington from the server.)

Two of the most notable features of RESTful web APIs are:

1. Semantic URLs - URLs - are designed to be intuitive and self-documenting.

There is an expectation that the reader will be somewhat familiar with the concepts that REST encompasses. There are many good online resources but there are just as many that fail to explore the full benefits of REST. In these cases, the resources favor a practical approach toward REST assuming that implementing a fully RESTful paradigm might be too difficult and therefore becomes a barrier for implementation. The Richardson Maturity Model is a nice article that helps explain REST in an easy to read format and offers a stepping-stone approach toward full REST implementation.

...