Rest API
Most APIs written this days are web apis. Don't quote me on that one because I didn't do any research to get a proper number. 😁 But given the number of web services and web application I don't think I am too far off.
What is REST
REST is acronym for REpresentational State Transfer. It is architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation.
Like any other architectural style, REST also does have it’s own 6 guiding constraints which must be satisfied if an interface needs to be referred as RESTful. These principles are listed below.
Guiding Principles of REST
Client–server – By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
Uniform interface – By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.
To see an example of a REST API we can use
HTTP Verbs
These are some conventions HTTP apis follow. These are actually not part of Rest specification. But we need to understand these to fully utilize Rest API.
HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred as HTTP verbs. Each of them implements a different semantic, but some common features are shared by a group of them: e.g. a request method can be safe, idempotent, or cacheable.
GETThe GET method requests a representation of the specified resource. Requests using GETshould only retrieve data.
HEADThe HEAD method asks for a response identical to that of a GET request, but without the response body.
POSTThe POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server.
PUTThe PUT method replaces all current representations of the target resource with the request payload.
DELETEThe DELETE method deletes the specified resource.
CONNECTThe CONNECT method establishes a tunnel to the server identified by the target resource.
OPTIONSThe OPTIONS method is used to describe the communication options for the target resource.
TRACEThe TRACE method performs a message loop-back test along the path to the target resource.
PATCHThe PATCH method is used to apply partial modifications to a resource.
THESE ARE ALL LIES.
Status Codes
This also has no actual meaning.
Terminologies
The following are the most important terms related to REST APIs
Resource is an object or representation of something, which has some associated data with it and there can be set of methods to operate on it. E.g. Animals, schools and employees are resources and delete, add, update are the operations to be performed on these resources.
Collections are set of resources, e.g Companies is the collection of Company resource.
URL (Uniform Resource Locator) is a path through which a resource can be located and some actions can be performed on it.
API Endpoint
This is what a API endpoint looks like.
https://www.github.com/golang/go/search?q=http&type=CommitsThis URL can be broken into these parts
protocol
subdomain
domain
path
Port
query
http/https
subdomain
base-url
resource/some-other-resource
some-port
key value pair
https
www
github.com
golang/go/search
80
?q=http&type=Commits
Protocol
How the browser or client should communicate with the server.
Subdomain
Sub Division of the main domain
Domain
Unique reference to identify web site on the internet
Port
Port on the server the application is running on. By default its 80. So most cases we don't see it
Path
Path parameters in a Rest API represents resources.
https://jsonplaceholder.typicode.com/posts/1/commentsposts/1/comments
This path is representing the 1st posts resource'c comments
Basic structure is
top-level-resource/<some-identifier>/secondary-resource/<some-identifier>/...Query
Queries are key value pairs of information, used mostly for filtering purposes.
https://jsonplaceholder.typicode.com/posts?userId=1Parts after the ? is the query parameters. We have only one query here. userId=1
Headers
This was not part of the URL itself but header is a part of network component sent by the client or the server. Based on who sends it. There are two kinds of header
Request Header (client -> server)
Response Header (server -> client)
Body
You can add extra information to both the request to the server and to the response from the server.
Response Type
Usually JSON or XML.
Now a days it's mostly JSON.
Last updated
Was this helpful?