RESTful API

Restful API is a Web Service architectural style to remotely interface with other applications using http protocol. It stands for REpresentational State Transfer Application Programming Interface. A Restful Webservice is much more than a HTTP call using JASON data transfer. It needs to confirm to certain design constraints to fully qualified to be called Restful.

A RESTful Web services provides access to its Web resources in a textual representation and the application that uses it could read and modify of them with a stateless protocol and a predefined set of operations supported by http. Communication back and forth is supported through text based structured format such as JSON, XML or HTML, JASON being the most common.

The above diagram shows this concept in detail.  A web resource resides in the server, an URI uniquely identifies it, and a client operates on it with given methods of HTTP protocol.

Further details, such as textual representation and state transfer is detailed in the next section. These concepts will be discussed as we progress through this article.

Representational State Transfer

This diagram visually shows the concept of RESTful Service.

Representational State transfer is a term introduced in 2000 by an American computer Scientist Roy Fielding in his dissertation. It means transferring an object being is certain state to another place.

Restful API works an object,  represented by an URI,  in certain state. Using http methods, you can transfer that object into a client of Restful Service. If needed the client can change the state of that object in the server via via predefined https operations, then again transfer it back. 

Key Terms of Restful API

Web Resource

An object that is the server. Example, BankAccount of a customer.

Textual Representation

The resource BankAccount may be stored in a Relational Database or in a No SQL Database. However, it has to be represented as text and must be decoupled with its representation in the database. This is done using formats such as JASON.

State

BankAccount has details such as account balance, account type, this is the state of that object. The state is changeable using REST methods. 

State Transfer

Current state of the object could be transferred to the client. 

Stateless Protocol

Restful APIs work using HTTP, which is a stateless protocol. When the client calls first time, it does the operations, the forgets about client. When the it calls the second time, client has to self identify if it needs to be recognized.

 In the web technologies, this is done using some sort of a session id that client sends to the server.

Why Rest API

Restful APIs have become preferred choice due its simplicity and intent for performance.  Restful Webservices is an alternate to SOAP based services and has become the mostly used approach since its adoption and powerful platforms that are faster, secure, complex yet easy to consume could be developed with Restful APIs.

A Restful API  is represents a web resource with a URI and standard http operations such as GET, POST, PUT, DELET are used to work on that resource. It is hosted on a http server to achieve this goal. Statelessness of http protocol, its standard operations and the simplicity of operating with JASON have made it very like by both the developer and Enterprises.

Being http protocol, Resftul APIs leverages already well-established standards, tools and frameworks to its advantage.

RESTful API Use cases

Where there is an integration need between applications or services, RESTful APIs could be used.  

Enterprise API Platform

Every enterprises from banking to car maker to service providers are trying to transform themselves into a tech company and expose their APIs to the Public, Customer and Partner Integration. Enterprises need an API platform for this purpose.

Resful APIs help Enterprises build their Cloud Service platform and expose their services. Since technical transformations and Cloud usages are on the rise, so are Rest services. A good platform will cover all API User Stories in detail.

Microservices Integration

Restful APIs are also used to integrate Micro Services together inside an organization. Micro Services help an application become modular and easily manageable. And the Restful APIs help them connect and communicate each other fulfill use cases of an entire application.

If an Enterprise if building a platform these set of APIs could become internal services while those exposed to outside will be external APIs.

Application Integration

Resftful APIs could be used to integrate applications in a platform and programming language agnostic way.

Rest API Tools and Technologies

As Rest APIs have become common industry has supported it with tools and technologies. Mulesoft intriduced RAML, Rest Markup Language for Rest specification. Swagger standard for Rest API eventually matured in to Open API Standard 3.0 and has become widely used in the industry. Mulesoft also adopted OAS3.0

Swagger UI is used to define Restful APIs in OpenAPI Standard. This could be converted to a boilerplate code using Swagger Codegen. Mock Testing is possible at this stage and it helps to validate what are you really going to develop in advance.

You could develop further using the boilerplate code generated to complete the functionality. There are many programming language and framework options during the development. Once it is developed it moves on cloud deployment, monitoring eventually by consumption by clients.

As mentioned earlier, Restful APIs are used to integrate Micro Services within an organization. However, when there are many microservices to interact with, the communication forms a complex network topology that is complex to manage. API Enablers solve this problem by providing a common hub to expose APIs.

AWS, Azure, Apigee are the example of API Enablers and all these API Enablers support Restful APIs. It will be hard to think of an any iPaaS provider or cloud provider without the support of Restful APIs for integration.

Rest Constraints

RestAPIs much confirm to six constraints to fully qualify to be called Rest: Client-Server Architecture, Statelessness, Cacheability, Layered System, Code on Demand, and Uniform Interface.  Code on Demand constraint is optional.

These constraints help a Restful Service attain much of its nonfunctional advantages such as modularity and performance.

Client-Server Architecture

Client-Server Architecture ensures separation of separation of concerns, application logic and enforces modularity. Restful webservice runs on a server which is consumed by a remote client. If client is changed there is no impact on the server. If the server is changed, as the interface is kept the same, there is no dependency on the client.

There is no need for the client to worry about data storage, scalability or architecture of the server, while client can focus on just consuming the service and make it available to end user through an UI. This also promotes portability across multiple platforms of client. From web to mobile the service is consumable through the same protocol.

Statelessness

Rest is built on http and this protocol is stateless. It means, the server does not try to remember the state between two client calls. This adds to the advantage of performance.

 For the same reason, each call must be made without the presumption of previous call. Session management is thus left to the client and is responsible to sending it to the server when needed.

 It must be however, noted that whatever state change the client requested in the previous call is still effective in the server.

Cacheability

Clients can take advantage of caching the response from the server to avoid round trip to server. This is in consistent with how a web protocol works. Thus, responses must implicitly or explicitly define themselves as cacheable or not to avoid client using any stale data.

Layered System

Generally, a http call will go through multiple layers of servers for security through firewall, or load balancing for scalability. This should not have any impact on the client or server.

Layered system constraint demands that a Restful Webservice will be operational without any code change is the underlaying infrastructure is changed.

Code on Demand

This is an optional constraint of Rest API. Based on the context, server include code as the part of the response which could be executed by the client. When this is done, it should be done after much consideration at the design time. This could intern mean a language dependency at the client side.

Uniform Interface

Uniform Interface constraint is defined with the modularity and decoupling of the interface in mind. It is further divided in to four and each could evolve separately.

 Resource Identification

Rest Interfaces work on a resource thus identification of the resource itself is an important part of the API design. A Rest APIs resource is uniquely identified using a URI. Also, a Restful Service must only standard operations such as GET, PUT, DELETE etc. be used to change its state. This keeps uniformity in resource identification.

The resource could be transferred to the client using representations in well formed structure text such as JASON, XML or HTML. It is important to understand that the actual representation of the resource is decoupled from its representation. For example, if a resource is stored in the Database, the interface should not be dependent on that representation.

Here, for example, if JASON is used to represent the resource, it will be independent of any database properties.

Resource manipulation through representations

Once the resource is identified and its state is transferred to the client, the client must have all the information to make further operation on the resource to change its state further. This constraint is meant for that purpose. That way, a service is intended to change resource property, the response it transferred while sending the resource state should have its unique identifier.

Self-Descriptive Messages

A Message in a Rest Webservice means, the actual API call itself. Each message must be self-descriptive. If the server is sending responses in JSON, the response must contain that it is Jason.

If the message contains other media type, it must also contain information how to process it. Communication using APIs will pass messages also based on the context. If a message is sent, it must also have details how to process it as well.

 This gives you the flexibility of defining your own media type, if necessary, as long as it the message contains enough information about the media and both server and client are in agreement to what media type refers to.

Hypermedia as the engine of application state (HATEOAS)

Generally, programmers think of Restful service as call over http using Jason for data transfer. Thus, HATEOAS in Rest is often overlooked constraint.

HATEOAS is an important concept without HATEOAS an API is not Restful. It simply means that the responses sent from the server must include links to subsequent services for the client to operate. This makes sure that given the entry point and basic understanding of the media type and the representation, the all other parts of service are self-discoverable.

When you design a rest API, keep these concepts in mind to follow RestAPI Design Best Practices.

REST Methods

Rest APIs methods are predefined http operations.

GET – gets the current state of the resource. Idempotent.

PUT – works on a single resource and for creation or changes of its state. Idempotent

DELETE – Deletes the specified object. Idempotent.

POST – works on a collection. Creates or updates a collection.

PATCH – updates a collection          

Developers are often confused on PUT vs POST. As a general practice take advantage of idempotency of PUT and use it for creation and POST for update.

Idempotent Law

While implementing a service, the Idempotent Law in Rest Services must be respected. Only specified operations should change the state of the resource. An operation that does not change the state of the resource is called Idempotent. In Restful Services, GET, PUT and DELTE operations are idempotent.

Rest API Security

Rest APIs could be internal or external based on the exposure. In either case, it must be secured. The security starts with establishing the connection. Since it is based on web technologies, the underlying security measures could be used here as well. https endpoint will ensure a secure connection using SSL or TLS.

 When it comes to authentication there are options such as Basic Auth, oAuth and JWT Token. How to Secure Rest API should be a well thought during your early phases of API development.

In the computing world, everyone wants high performing systems and REST APIs are not different. To achieve this, standard performance methods must be employed. This include tuning the database , using better performing infrastructure and scalable architecture.

RESTful properties such as cacheablity could be used to tune performance further. If the client can avoid round trip to the server caching the response that will improve the performance. So is the case, when the responses could be compressed and passed to the client, resulting in lesser bandwidth and thus faster response.

What REST is not