What is RESTFUL API ?

#api #php #graphql #restful

RESTFUL api stand for representational state transfer is the name of the method used to communicate with the apis. as the name suggests, it is stateless. in other words, the services do not keep the state that transferred, so if you call api sending data, the same api will not remember the data next time you call it. The state is kept by the client. a good example of this is when a user is logged in and the user is able to call a specific method, so it is necessary to send the user credentials (username and password or token) every time.
creating a restful apis will be easier for you and the consumers if you follow some conventions in order to make them happy. i have been using some recommendations on restful apis and the results were really good. they help to organize your application and its future maintenance needs. also your api consumers will thank you when they enjoy working with your application.

security in your restful api is important, but it is especially important if your api is going to be consumed by people you do not know, in other words, if it is going to be available to everybody.
use ssl everywhere it is important for the security of your api.
there are many public places without an ssl connection and it is possible to sniff packages and get other peoples credentials.
use token authentication, but it is mandatory to use ssl if you want to use a token to authenticate the users. using a token avoids sending entire credentials every time you need to identify the current user. if it is not possible, you can use oauth2.

in your restful api is important to follow this standards:-

use json everywhere. avoid using xml. if there is a standard for restful apis, it is json. it is more compact, can be easily loaded in web languages and easy to understand by humans.
use camelCase instead of snake_case; it is easier to read.
use http status code errors. There are standard statuses for each situation, so use them to avoid explaining every response of your api better.
include the versioning in the URL, do not put it on the header. The version needs to be in the url to ensure browser exploitability of the resources across versions.
use Http Method for each situation ( POST, GET, PUT, PATCH, DELETE ).
avoid using session or save state in the server.
avoid using bool flages to show success or failed requests, replace it with http status codes.

Top comments (2)

peerreynders • Mar 4 '22

In 2007 RESTful Web Services was published and described REST as (p.105) (or resource oriented archtiecture (ROA); ROCA);

It's just four concepts:

Resources
Their names (URIs)
Their representations
The links between them

and four properties

Addressability
Statelessness
Connectedness
A uniform interface

Resources (p.81): If it's important enough to be referenced "by itself" then it should be a resource with its own unique name/identity.
Addressability (p.84): Resources have to be referenced somehow. In the case of the Web the resource's URI (p.81) becomes its URL.
Representations (p.91): Often the actual "resource" cannot be manipulated directly. So instead the resource is manipulated through one of it's "Representations". The resource representation can be simultaneously published in multiple formats like XHTML, XML, JSON or any other IANA MIME media type. However strong preference is given to media types that support another REST property - connectedness; the representation format should allow for standardized links to other resources. In the case of the Web you want to the format to expose URIs in a standard way (e.g. HTML's anchor element). To change a resource's state you retrieve the representation, modify it, and write it back.
Statelessness (p.86): No server-side application (client) state. The only state that exists on the server is resource state (which is captured in its representation). Application state stays on the client.
Links and Connectedness (p.94) of resources (hypermedia as the engine of application state - HATEOAS): Any resource can and should link (in it's representation) to other resources (via the URIs). A RESTful application tends to have one single root resource where each "session" starts. The possible client application state transitions are described as links to other resources inside each resource's representation. So the navigation from one resource to the next is what is changing (and defining) application/client state.
Uniform Interface (p.97) exposed by resources: Every resource implements the same Uniform Interface (or at least a significant subset). In the case of the Web, the Uniform interface is defined through the HTTP methods (GET ,PUT, DELETE etc.) - one should stick with the safe and idempotent methods whenever possible.

In some ways the article is focusing more on contemporary implementation patterns, practices and technologies used by general APIs-over-HTTP that may claim to be RESTful. Sometimes that claim comes from tooling that tries to position itself in the "RESTful" space - e.g. Swagger ain't REST - is that OK?. Quite often APIs are just a collection of documented URI templates with JSON responses while completely lacking the hypermedia aspect (links and connectedness) inside the representation.

This isn't about some standard of absolute purity but the fact the term RESTful doesn't really communicate anything useful these days. The idea behind REST is an architecture that's aligned with the nature of the web of interconnected resources rather than just tunnelling RPC as JSON payloads over HTTP. REST is data-oriented so it isn't suitable for all API styles (resource design for transactions).