.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
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
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 :
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:
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 :