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 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 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(orPOST)/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:
- 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.
The SRP HTTP Framework is designed around the REST API model but it does not enforce it. Indeed, it can nicely work with any API methodology and replace the standard RUN_OECGI_REQUEST (i.e., INET) utility, although some additional work would need to be done to replace pre-built INET routines. Note, while the SRP HTTP Framework can support INET style applications, RUN_OECGI_REQUEST cannot support REST APIs. The primary reason is that RUN_OECGI_REQUEST intentionally obscures the URL in favor of the INET routine that is named in the end point. Hence, there is no easy way to glean semantics out of the rest of the URL, which makes RESTful approaches useless.
Whether or not implementing a comprehensive REST API is intended, developers are strongly encouraged to consider some type of REST design in their web applications for two reasons: 1.) REST is arguably a formalized explanation of the way the internet (via HTTP) is meant to be used. It lays out the principles by which the internet has become so robust, scalable, and accessible. 2.) While REST has been documented for quite some time, there seems to be a significant resurgence of interest in this architecture from small and large online service providers. This is hugely beneficial to the OpenInsight developer because it taps into a reputable and credible methodology that obscures the underlying technology (i.e., Basic+, Linear Hash) that is often a barrier to mainstream acceptance.
