In this tutorial, we are going to talk about some important topics such as API, REST, RPC, HTTP Methods...
API(application programming interface)
An API is an interface that enables applications to exchange data among each other. Many companies use an apı to speed up their jobs. They can constrain and extend access depending on the authorization. By using an API, we constrain clients to access directly to our applications. So, how do applications communicate among each other? Depending on needs, some companies prefer JSON, XML, SOAP, RPC... If an API conforms rest standards, it is called restful.
JSON
JSON stands for Javascript object notation, is a lightweight data-interchange format. It stores data key/value form. For instance, i added a sample of json data.
{
students:[
{
'id':1,
'FirstName':'Bob',
'LastName': 'Marley',
'Job': 'Musician'
},
{
'id':2,
'FirstName':'Bob',
'LastName': 'Dylan',
'Job': 'Musician'
}
]
}
XML
XML is the abbreviation of extensible markup language. It ıs also store and transport data. If you know about HTML, it would be easy to read and understand an XML file. It would be better to apply standards and extensions of XML to benefit from the power of XML.
<students>
<student>
<firstName>Bob</firstName> <lastName>Marley</lastName><Job>Musician</Job>
</student>
<student>
<firstName>Bob</firstName> <lastName>Dylan</lastName><Job>Musician</Job>
</student>
</students>
gRPC
It is an open-source, high-performance framework that makes it easier for us to create distributed applications and services. It is used to serialize structured data. Being a protocol based on a binary makes it faster than text-based protocol. It's even faster than JSON.
Details Details on Microsoft Docs Protocol-buffers
Soap
Soap stands for simple object access protocol. Briefly, it's based on XML that enables to exchange data among the computers. There are several advantages of soap like platform and language independent. Soap provides data transports, enables connections between different endpoints.
Rest(Representational State Transfer)
It ıs an architecture style that has following constrains:
- Uniform interface
- Client–server (Client and server side must be open to develop independently.)
- Stateless (A request should contain all necessary information to service the request.)
- Cacheable
- Layered system
Best-practices/api-design rest-api-standards-do-they-even-exist Best-practices-for-rest-api-design
Uniform Resource Identifier (URI)
In an API design, clients must access resources using a hierarcical order. For instance:
https://my-api.com/api/v1/users/123456/books.
- Do not use underscore(_)
- Collections are specified in the URL with plural names.
- A Document is specified in the URL with a singular name.
- Do not use camel case
- Allow filtering, sorting, and pagination
- Nest resources for hierarchical objects
…
HTTP Methods
Let's start learning some key words like idempotent, Safe, Cacheable...
Idempotent
An HTTP method is idempotent if an identical request can be made once or several times in a row with the same effect while leaving the server in the same state.
If the result does not change when you make one or more requests, we call this HTTP method idempotent. Here are some examples of idempotent methods: GET, HEAD, PUT, DELETE, OPTIONS, TRACE.
GET
The HTTP GET method is used to retrieve data from a specified resource. For security reasons, do not use GET method to send pieces of information like email and password because your email and password will be shown on the search area as below.
https://www.example.com/login/?username=baris&password=1234
If a client requests a product having id=2, the server will return the data below as a response.
{
"id": 2,
"categoryId": 3,
"productName": "Phone",
"publishingDate": "2022-01-13T10:49:38.6979609+03:00"
}
HEAD
It's similar to GET method, but the response does not have a message body. It's often used to retrieve meta-data. Meta-data might contain information about keywords, content-type, page description, author, viewport, content-encoding...
PUT
The PUT method enables us to send data for update operations. If an error occurs while creating an object, you can return HTTP 500 status code.
[HttpPut("{id}")]
DELETE
It ıs used to delete a specified resouces.
[HttpDelete("{id}")]
OPTIONS
The OPTIONS method describes the communication options for the target resource.
Non Idempotent
POST
The HTTP POST is used to send data to the server. If you create a new object, you can return HTTP 201 status code.
[HttpPost]
PATCH
It’s used to update partial informations from a specific resource.
[HttpPatch("{id}")]
Safe
An HTTP method is safe if it doesn’t alter the state of the server. In other words, a method is safe if it leads to a read-only operation.
Cacheable
A cacheable response is an HTTP response that can be cached, that is stored to be retrieved and used later, saving a new request to the server.
Common HTTP Status Codes
200: This code indicates that the request is successful.
return Ok()
400: If a client enters an invalid request, we see this code.
return BadRequest()</br>
401: If a unauthorised user tries to access a resource, the server usually returns this code. I added an example of the way that we return the status 401 code.
[HttpGet("/panel/{authorization}")]
public IActionResult HowToReturn401(string authorization)
{
if (authorization=="user")
{
return Unauthorized();//401
}
return Ok();
}
403: If a user is auhenticated, but it’s not allowed to access a resource. Suppose that a user is not allowed to access vip panel, the server can return the status 403 code as below.
[HttpGet("/panel/vip/{authorization}")]
public IActionResult HowToReturn403(string authorization)
{
if (authorization == "user")
{
return StatusCode(403);// Forbidden
}
return Ok();
}
404: Not Found
return NotFound();
500: Internal server error
return StatusCode(500);
502 Bad Gateway – This indicates an invalid response from an upstream server.
return StatusCode(502);
503: Service Unavailable
[HttpGet("/admin")]
public IActionResult HowToReturn503()
{
return StatusCode(503);
}