Reference:
https://www.sitepoint.com/developers-rest-api/
https://www.mulesoft.com/resources/api/what-is-rest-api-design
https://www.quora.com/What-is-a-REST-API
The advantages of REST for development
1. Separation between the client and the server: the REST protocol totally separates the user interface from the server and the data storage. This has some advantages when making developments. For example, it improves the portability of the interface to other types of platforms, it increases the scaleability of the projects, and allows the different components of the developments to be evolved independently.
2. Visibility, reliability and scaleability. The separation between client and server has one evident advantage, and that is that each development team can scale the product without too much problem. They can migrate to other servers or make all kinds of changes in the database, provided the data from each request is sent correctly. The separation makes it easier to have the front and the back on different servers, and this makes the apps more flexible to work with.
3. The REST API is always independent of the type of platform or languages: the REST API always adapts to the type of syntax or platforms being used, which gives considerable freedom when changing or testing new environments within the development. With a REST API you can have PHP, Java, Python or Node.js servers. The only thing is that it is indispensable that the responses to the requests should always take place in the language used for the information exchange, normally XML or JSON.
REpresentational State Transfer (REST)
https://techtalk.vn/thiet-ke-restful-apis.html
+ HTTP, URI, JSON, and XML
+ HTTP: Hyper Text Transfer Protocol
+ XML: eXtension Markup Language
+ JSON: JavaScript Object Notation
+ URI: Uniform Resource Identifier
+ HTTP GET: Get resources
+ HTTP POST: Create a new resource
+ HTTP PUT: Edit resource with all fields (10 fields)
+ HTTP PATCH: Edit resource with some fields (2 fields)
+ HTTP DELETE: Delete a resource
+ HTTP Caching: Entity Tags (ETags), Redis & MemCache
http://www.freshblurbs.com/blog/2015/12/12/http-cache-restful-apis.html
http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html
+ ASP.NET Web API | ASP.NET Core Web API, OData, OAuth, OAuth2
An architectural style called REST (Representational State Transfer) advocates that web applications should use HTTP as it was originally envisioned. Lookups should use GET requests. PUT, POST, and DELETE requests should be used for creation, mutation, and deletion.
+ What's OData?
OData (Open Data Protocol) - the best way to REST.
An open protocol to allow the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way.
+ What's OAuth?
An open protocol to allow secure authorization in a simple and standard method from web, mobile and desktop applications.
+ What's OAuth2?
The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service.
OAuth
One of the downsides of hmac is that there are no more passwords, but just plain secrets. When johns secret gets out, everyone could use that secret to access the account of john. A common way to prevent this is to use temporary tokens. John "asks" the server for a "token" and "secret", and with these token and secret, it is allowed to access its protected resources.
OAuth is a mechanism that allows you to create temporary tokens. It is a common used scheme for authentication and authorization, however the OAuth(1.1) specification is a bit difficult to implement for beginners. However, many libraries in pretty much every language exist to make this much easier to implement.
OAuth2
Even though the name suggests its the next version of OAuth, the whole structure has changed radically and cannot even be considered a new version. OAuth2 is a complete new way of authentication which is easier to implement and maintain. However, OAuth2 is not officially a standard yet, although many sites and organizations are using the current drafts.
Caveats
- Basic authentication and OAuth versions MUST be protected through SSL/TLS. They should not be used over plain HTTP.
- Using nonces can improve your security, but you MUST store and compare nonces server-side.
- A common issue when using time-windows for request, is that either server or client is not using the correct time. Make sure both server and client are using systems like NTP to keep times in sync
RESTful APIs
Refer: https://www.toptal.com/laravel/restful-laravel-api-tutorial
First, we need to understand what exactly is considered a RESTful API. REST stands for REpresentational State Transfer and is an architectural style for network communication between applications, which relies on a stateless protocol (usually HTTP) for interaction.
HTTP Verbs Represent Actions
In RESTful APIs, we use the HTTP verbs as actions, and the endpoints are the resources acted upon. We’ll be using the HTTP verbs for their semantic meaning:
- GET: retrieve resources
- POST: create resources
- PUT: update resources
- DELETE: delete resources
Update Action: PUT vs. POST
RESTful APIs are a matter of much debate and there are plenty of opinions out there on whether is best to update with POST, PATCH, or PUT, or if the create action is best left to the PUT verb. In this article we’ll be using PUT for the update action, as according to the HTTP RFC, PUT means to create/update a resource at a specific location. Another requirement for the PUT verb is idempotence, which in this case basically means you can send that request 1, 2 or 1000 times and the result will be the same: one updated resource in the database.
Resources
Resources will be the targets of the actions, in our case Articles and Users, and they have their own endpoints:
- /articles
- /users
In this laravel api tutorial, the resources will have a 1:1 representation on our data models, but that is not a requirement. You can have resources represented in more than one data model (or not represented at all in the database) and models completely off limits for the user. In the end, you get to decide how to architect resources and models in a way that is fitting to your application.
A Note on Consistency
The greatest advantage of using a set of conventions such as REST is that your API will be much easier to consume and develop around. Some endpoints are pretty straightforward and, as a result, your API will be much more easier to use and maintain as opposed to having endpoints such as GET /get_article?id_article=12 and POST /delete_article?number=40. I’ve built terrible APIs like that in the past and I still hate myself for it.
However, there will be cases where it will be hard to map to a Create/Retrieve/Update/Delete schema. Remember that the URLs should not contain verbs and that resources are not necessarily rows in a table. Another thing to keep in mind is that you don’t have to implement every action for every resource.
