Let’s approach this step-by-step by first understanding what is an API

Now suppose you want a PayPal payment option available to your customers on your website checkout page, so what do you do?

You simply login to your company’s online PayPal account and grab your account’s secret API key(which acts as a bridge between your Website and PayPal account)

After copying your secret API key, you go to the integration settings on your website builder(or download a plugin that allows this feature) and paste your API key in the space provided(like shown in the image below), and that’s it…

Congratulations! Your website is now ready to collect payments via PayPal and send them straight to your bank account.

Honestly, how convenient and cool is that…

 

Now, to understand Rest API, What is Rest API used for & API vs Rest API let’s further look at what are ‘Web Services’

As you may know, web applications are developed using variety of programming platforms like, Java or MicrosoftASP.net, and since they’re developed using different development languages it becomes difficult to ensure active communication between these applications

This is where web services come in because Web Services provide a common platform that allows multiple applications built on various programming languages to have the ability to communicate with each other.

And this is where Restful web services come in, where Rest stands for ‘REpresentational State Transfer’, It is a set of rules developers follow when they create an API

Rest is just a pattern for making APIs and by using this API you can access resources like image, post, video, text content and so on…

So, Restful meaning is: “The services that use RestAPI to communicate”

A service built on REST architecture is called a RESTful service or API created using REST pattern is known as Rest API

Most Rest API services use http request

Again, Restful API is important because it enables web applications that are built on various programming languages to communicate with each other.

Just like its explained using the example of your Website and PayPal above.

 

Restful API Design and Architecture

REST has its own guiding principles and constraints like other architectural styles and these principles must be satisfied.

REST APIs can be developed using virtually any programming language and support a variety of data formats. The only requirement is that they align to the following six REST design principles – also known as architectural constraints:

 

• Uniform Interface

This is a key constraint which differentiates between Rest API and Non-Rest API by suggesting that there should be a uniform way of interacting with a given server irrespective of the device or type of application (i.e. mobile app or a website)

And Uniform interface does that by imposing four architectural constraints:

• Resource-Based:

  The interface must uniquely identify each resource involved in the interaction between the client and the server.

   

• Manipulation of Resources Through Representations:

  Clients have sufficient information in the resource representation to modify or delete the resource if they want to. For eg: Usually subscribers(resource) are assigned their unique id on a website, so, when a user requests a particular subscriber, then they use that id to delete or modify their information.

   

• Self-descriptive Messages:

  Each message includes enough information to describe how to process the message so that server can easily analyze the request. It should also provide information of the additional actions that the client can perform on the resource.

   

• Hypermedia as the Engine of Application State (HATEOAS):

   HATEOAS keeps the REST architecture unique from most other network application architectures.

The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text.

Navigating hypermedia links is conceptually the same as browsing through web pages by clicking the relevant hyperlinks to achieve a final goal.

 

• Client Server Decoupling

A Client is someone who is requesting resources and are not concerned with how those resources are stored(which is the job of the server), and server is someone who holds the resources and are not concerned with the user interface or user state.

The client-server constraint works on the concept that the client and the server should be separate from each other and allowed to evolve individually. 

 

• Statelessness

Statelessness constraint mandates that each request from the client to the server must contain all of the information necessary to understand and complete that request.

So the calls made by client to server are independent of one another, and each call contains all of the data necessary to complete itself successfully.

Clients can request resources in any order, and every request is stateless(isolated) from other requests.

 

• Cacheability

This function is similar to how your web browser works, for eg: when you enter a website URL, your browser downloads its information from the internet(which takes a few seconds) however, your browser stores some of the website information(say images) in the system cache memory which helps the same website load much faster the next time you open it.

Similarly, RESTful web services support caching, which helps store some responses on the client to improve server response time.

The cacheable constraint requires that a response should implicitly or explicitly label itself as cacheable or non-cacheable.

If the response is cacheable, the client application gets the right to reuse the response data later for similar requests and a specified period.

 

• Layered System Architecture

An application architecture needs to be made of multiple layers, with each layer having a specific functionality and responsibility. 

For eg: a layered system architecture allows you to deploy the APIs on server A, store the data on server B and authenticate requests in Server C.

Layers can be added, removed, modified, or reordered as the architecture evolves.

In a layered system, each layer cannot see beyond the immediate layer they are interacting with.

Also, providing substantial security benefits, allowing you to stop attacks by keeping critical and more vulnerable aspects of your architecture behind a firewall, preventing direct interaction with them by the client.

 

• Code On Demand

As the name suggests, servers can provide executable code to the client(the client only needs to execute the code), creating a smart application that is no longer solely dependent on its own code structure.

This downloaded code simplifies clients work by reducing the number of features required to be pre-implemented.

 

How Rest API’s Work

REST APIs communicate via HTTP requests to perform operations like Creating, Reading, Updating and Deleting records (also known as CRUD) within its resources(database). 

As you can see above RESTful system consists of a:

• Client who requests for the resources.
• Server who has the resources.

And it uses commands to obtain resources by using HTTP Method

Every https request has an verb/method that determines its type or intention

Here are some of the common HTTP methods/verbs described below:

• GET to retrieve a resource;
• PUT to change the state of or update a resource;
• POST to create that resource; and
• DELETE to remove it.

Get(Read): Is used for getting data.

So, to get the list of all customers we should send a http GET request to this address(GET /api/customers)

Note the plural name customers here indicates a list of customers 

So when we send a http GET request to this end point our service will send us something like this:

[ 

{ Id: 1, name: ‘Sorin’ } ,

{ Id: 2, name: ‘Sean’ } ,

…

]

Giving us an array of customer objects

If we want a single customer, we should include the ID of that customer in the address (GET /api/customer/1, Notice customer ID “1” at the end) 

Then our server will respond with a customer object like this:

[ 

{ Id: 1, name: ‘Sorin’ }

]

Post(Create): Is used for creating data

And to create customer we need to send a http POST request to this end point:

POST /api/customers

Note that because here we’re adding customers (thus not dealing with a specific customer), so we don’t have the ID and the address… 

…we’re working with a collection of customers , so we are posting a new customer to this collection and that’s why we should include the customer object in the body of the request:

{ name: ‘Aliya’ }

The server gets this object and creates the customer for us;

[ 

{ Id: 3, name: ‘Aliya’ }

]

Put(Update): Is used for updating data

Now, to update a customer we should send a http PUT request to this end point

PUT /api/customer/1

Note that again here we specify the ID of the customer(i.e. “1”) to be updated 

But also we should include the customer object in the body of the request, like so:

{ name: ‘Sean’ } (remember Id :1” was attached to a customer named Sorin before)

So, this is a complete representation of the customer object with updated properties

We send this to the server and the server updates the customer with the given ID according to these values:

[ 

{ Id: 1, name: ‘Sean’ }

]

Delete(Delete): Is used for deleting data

Similarly to delete a customer we have to send a delete request to this end point:

DELETE /api/customer/1

But here we don’t need to include the customer object in the body of the request because all we need to delete a customer is their ID

Rest API Challenges

A REST API is designed to be very flexible, but even besides there design and architectural constraints, individuals will have to confront some challenges with REST APIs, and these may include;

 

Security: 

Security has to be simultaneously integrated while building an API(as it can’t be updated later) because a broken or hacked API can result in millions of dollars in fines to a business.

So, it includes a lot of aspects like;

• Blocking access to unknown IP addresses and domains,
• Blocking unexpectedly large payloads,
• Investigating failures,
• Validating URLs, and
• HTTPS

 

API Versioning:

Softwares update and so do APIs. APIs must support both breaking and non-breaking changes in a way that it does not cause problems for the developers and its users

Versioning allows you to make breaking changes to the API without impacting current users(future users won’t be affected by this as they will be using the updated version).

 

Large Volumes of Data and Increased Response Times:

Overtime as the business grows the amount of data we collect and return is likely to increase as well, so the more data we are requesting and returning the slower the API will potentially become.

 

Endpoint Consistency:

Endpoints or individual URIs (Uniform resource identifier) need to be created in a way so they are consistent. 

So, it’s recommended to:

• Pluralise the entity names, such as “books” instead of “book”(remember this command “POST /api/customers”… here we have named the entity as customers)
• Verbs should never be used in URIs(so don’t have endpoints like “/api/postCustomers“ instead use the HTTP verbs and write “POST /api/customers”)

And because the paths of endpoints have to be consistent by following common web standards, it may make them difficult to manage.

 

Conclusion

RESTful web services are very popular because they are light weight, highly scalable and maintainable, thus very commonly used to create APIs for web-based applications.

It helps clients and servers exchange representations of resources by using a standardized interface and protocol (typically HTTP is the most used protocol)