Overview

• 1: What is REST?
• 2: Why REST?

1 - What is REST?

REST - Representational State Transfer - is a paradigm that enables abstract and structured communication between applications. The core of REST is to create a unified contract so that senders and receivers can exchange content in a consistent manner.
It is based on HTTP.

Although REST originated in 2000, it has only been widely used since around 2012. REST is considered the successor to SOAP and is today’s de facto standard for HTTP-based API communication; however, there are (better) alternatives depending on the use case.

Beginnings

The original design was based on the presumption that all the necessary capabilities for the beginnings of REST were already provided by HTTP, XML or the general HTTP client functionality in browsers and applications.
REST has now evolved much that content is now delivered in the more efficient Json and rarely with XML.

// https://my-rest-api.com/v1/task
<Tasks>
  <Task Id="123" isDone="false">
    <Title>Buy apples</Title>
    <CreatedOn>2018-04-26T16:47+00:00</CreatedOn>
    <!-- ... -->
  </Task>
<Tasks>

Most important principles

REST uses HTTP features and capabilities for content exchange.

Statelessness

REST is based on HTTP statelessness, which means that a REST request or message must contain all the information necessary for the server and/or client to process the request. This means at the same time that a client does not contain any information after a response when a resource changes. A client must request the resource again for updates.

Addressability

Each resource has a unique address that can be created, requested, modified or deleted via the URL. This simplifies the generalized and standardized construction of web interfaces and the secure as well as correct exchange of resources.

HTTP verbs (GET, POST, PUT, DELETE…) are used in addition to the address.

Sample:

Representation

Regardless of an address to a resource, it can be delivered in different structured representations, but all of them must be HTTP-compatible and thus text-based. So the REST API is free to deliver HTML, XML or Json…. for example, or dynamically with both.

<Tasks> <!-- This is the collection -->
  <Task Id="123" isDone="false"> <!-- This is the item -->
    <Title>Buy apples</Title>
    <CreatedOn>2018-04-26T16:47+00:00</CreatedOn>
    <!-- ... -->
  </Task>
<Tasks>

[ // this is the collection
  { // this it the item
    "Id" : 123,
    "IsDone" : false,
    "Title": "Buy apples",
    "CreatedOn" : "2018-04-26T16:47+00:00"
  }
}

Conclusion

REST represents an HTTP standardization for exchanging information between applications - for example, a server and a client - in a structured manner.

2 - Why REST?

REST, or Representational State Transfer, is a software architectural style that defines a set of constraints to be used for creating Web services. REST is based on the HTTP protocol, and it uses HTTP methods to manipulate data stored on a server.

There are several reasons why you should consider using REST in your HTTP API - based on your use case:

• REST gives you a strict paradigm of what an API should look like
• REST is widely adopted: REST has become the de facto standard for building APIs, and it is supported by a wide range of client libraries and tools. This makes it easy for developers to use and interact with your API, as there is a wealth of resources available for learning how to use REST.
• REST is flexible: REST does not prescribe a specific way of implementing an API, and it allows you to design your API in a way that best fits your needs. This means that you can choose the right data formats, authentication methods, and other features for your API, making it easier to build and maintain.
• REST is scalable: REST APIs are designed to be scalable, and they can handle a large number of requests without experiencing performance issues. This is important if you expect your API to be used by a large number of users or if you expect to add more features to your API over time.

Here is an example of a simple REST API implemented using ASP.NET Core and JSON:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;

namespace MyAPI.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class CustomersController : ControllerBase
    {
        // GET api/customers
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "customer1", "customer2" };
        }

        // GET api/customers/5
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "customer" + id;
        }

        // POST api/customers
        [HttpPost]
        public void Post([FromBody] string value)
        {
            // Add a new customer
        }

        // PUT api/customers/5
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
            // Update an existing customer
        }

        // DELETE api/customers/5
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
            // Delete a customer
        }
    }
}

In this example, the CustomersController class defines a set of actions for interacting with customer data. The [Route("api/[controller]")]attribute specifies the base URL for the API, and the[HttpGet], [HttpPost], [HttpPut], and [HttpDelete] attributes indicate which HTTP methods are supported for each action.

The Get action returns a list of customer names, and the Get(int id) action returns the name of a specific customer based on the id parameter. The Post action adds a new customer, the Put action updates an existing customer, and the Delete action removes a customer.

The limits of REST

While REST is a widely adopted and effective architectural style for building APIs, it is not suitable for every use case. Here are some potential disadvantages of using REST:

• REST is a paradigm designed primarily for querying and manipulating data structures. However, actions (e.g. uploading an image, sending an email, ping) are not part of the REST paradigm (e.g. the URL structures).

• REST can be very complex to implement: While REST is flexible and allows you to design your API in a way that best fits your needs, this can also make it more complex to implement. You need to consider factors such as data formats, authentication methods, and error handling, which can be time-consuming and require a lot of planning.

• REST does not provide real-time communication: REST APIs are designed for request-response communication, meaning that the client sends a request to the server and waits for a response. This means that REST is not well-suited for use cases that require real-time communication, such as chat applications or online gaming.

• REST is not always the most efficient: REST APIs are typically built around the CRUD (create, read, update, delete) model, which can be inefficient for certain use cases. For example, if you need to retrieve a large amount of data from a server, it may be more efficient to use a different communication protocol such as WebSockets or Server-Sent Events.