.NET Core RESTful APIs

A .NET Core Guide to Architect a RESTful API
Because, Great API’s depend on great architecture.
– Understand what an API is.
– Understand what is REST and what makes an API ‘RESTful‘.
This chapter is part of the .NET Core series.
Ch - 3
Implementing the Clean Architecture
Understanding the clean architecture and its use in a project
The Web Architecture

The Web as portrayed above can be simplified in understanding by thinking of it as thousands of small-scale, simple interactions between agents and resources using the founding technologies of HTTP and the URL.
It consists of multiple middleware servers like cache, content delivery networks, proxies etc to manage the traffic flow and for scalability.
Here, the resources are the fundamental building blocks of the overall system. They are uniquely identified in the network using a URI (note the http:// … in the above figure) and are capable of being manipulated using an application protocol (example: the web’s predominant protocol – HTTP).
System interactions and information exchange takes place using HTTP methods (verbs) – GET, POST, PUT, DELETE, OPTIONS, HEAD, TRACE, CONNECT and PATCH.
What is an API
An API stands for Application Programming Interface.
It is an important part of a modern web application and is responsible to do all the heavy lifting stuffs like driving the flow of information to and from various connected clients.
In the simplest of terms, An API is a software intermediary that allows multiple applications to talk with one another through the endpoints that are exposed by that API.
Data is transmitted among one another using various messaging systems that are defined by the API’s protocols. Some of the common data formats are HTML, XML, JSON etc.

Clients & Resources
-
Clients
For an API, Anything or anyone that calls the API and requests any kind of resource is a Client.
-
Resources
A Resource can be any object or its information that the API can provide to the caller.
The Endpoint
An endpoint is simply a connection point (a URL) exposed by the API in order to serve the requested resource.

Types of API's
API’s are mainly categorized based on constraints, architecture styles and their messaging protocols.
Based on Constraints
-
Open API's
Publicly available API's with no any restrictions.
-
Partner API's
Available to selected business partners.
-
Internal API's
Available only within an enterprise
Protocols & Architecture Styles

From Web ⇒ to REST
REST describes the Web as a distributed hypermedia application whose linked resources communicate by exchanging representations of resource state.
The term REST was first introduced by Dr. Roy Fielding in his 2000 doctorate dissertation.
He generalized the architecture principles of the Web and presented them as a framework of constraints or as an architectural style.
Fielding's descriptions :
-
The Web's Protocol
He described the operation of a distributed information system such as the Web and how they are built.
-
Using Resources And URI's
He described the interplay between resources and the role of unique identifiers in those systems
-
Communicating via HTTP methods
He talked about using a limited set of operations to build a ubiquitous infrastructure that can support any type of application. (Http methods - GET, POST, PUT and DELETE)
Roy Fielding referred to this architecture style as Representational State Transfer.
The Web’s Predominant Protocol + Resources and URI’s + HTTP Verbs + Guiding Constraints ⇒ REST
REST in Simple Terms
Simply speaking – When a client ( any device or software ) calls a REST API, the API will transfer to the client a representation of the state of the requested resource. This representation can be in any format such as JSON, XML, HTML, Plain text, MP3, JPEG etc.
How the server acts upon a client’s request depends on two things that a client uses:
-
A Resource Identifier
An endpoint or a URL (Uniform resource locator) to identify the resource.
-
An Action
The action that the client wants the server to perform ( In the form of an HTTP method or verb - GET, POST, PUT, DELETE ).
As a Client progresses through the application by requesting resources to the API (eg: http://abc.com/onions/1) and performing resource operations (state transitions) such as GET or POST, it will result in the next resource’s representation (next application state) being transferred to the Client.
What Makes An API RESTful
If an API is designed to process and respond to client requests using 6 guiding constraints, it can be considered a RESTful API. If the system violates any one of these 6 constraints, it cannot be considered a RESTful API.
Client-server architecture
The client doesn’t need to know anything about the business logic and the server doesn’t need to know anything about the front-end UI.
Uniform interface
There should be a uniform way of interaction with a given server irrespective of the device or the type of application (website, mobile etc).
Code on demand (optional)
Server can provide executable code as scripts to the client.
Layered system
The client can have access to the endpoint and the resources without having to accommodate to the underlying complexities that are required to generate that response.
Cacheability
Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side. This way, responses can be cached by the client if the information on the server has not changed since the last request.
Statelessness
The server does not remembers a client's activity (retain any kind of information) between requests.
There should be a uniform way of interaction with a given server irrespective of the device or the type of application (website, mobile etc).
The client doesn’t need to know anything about the business logic and the server doesn’t need to know anything about the front-end UI.
The server does not remembers a client’s activity (retain any kind of information) between requests.
Every response should include whether the response is cacheable or not and for how much duration responses can be cached at the client side.
This way, responses can be cached by the client if the information on the server has not changed since the last request.
The client can have access to the endpoint and the resources without having to accommodate to the underlying complexities that are required to generate that response.
Server can provide executable code as scripts to the client.
A Uniform Interface
Uniform Inteface is one of the key constraints that differentiates a REST API from a Non-REST API. It consists of 4 parts :
-
Identification Of Resources
Each resource should be uniquely identified through a URI.
(example: api/users/133) -
Manipulation Of Resources Through Representations
Client should obtain a representation of the resource along with enough information to further act upon the resource.
(permissions to modify, delete etc) -
Self-Descriptive Messages
Each message includes enough information to describe how to process the message.
(example: which parser to invoke can be specified by a media type) -
Hypermedia As The Engine Of Application State (HATEOAS)
Server needs to send hyperlinks in addition to data in its response to the client such that the client can then self discover the different operations that are available on the API and dynamically navigate through them.