RESTful API and REST Are Different.

• Readers who have heard about RESTful API countless times and vaguely know what it is but want to understand it precisely
• Readers who don't know the difference between REST and RESTful API

API (Application Programming Interface) refers to an interface for communication between two or more computer programs. For example, when you want to use the feature to search for a specific location on Kakao Maps or retrieve book information through Naver Search, the defined rules about how to send the search query and how the information is delivered are the API.

Source: KAKAO Local API Documentation

RESTful API refers to an API built based on REST architecture. Since RESTful API is often shortened to REST API, REST and RESTful API are often understood as the same thing.

However,

• REST is an architecture that defines what rules should be followed when communicating over a network,
• RESTful API is an API designed following the conditions of REST architecture.

Roy Fielding, who first defined REST architecture, participated in creating the standards for HTTP and URI, so the architecture created to maximize the advantages of HTTP and URI (caching, identification, HTTP Verb, etc.) is REST.

Roy Fielding defines the conditions of REST in his thesis as follows:

The client that handles user interaction and the server that manages data logic must be independent of each other. For example, let's say there's a button on a fruit shop website that retrieves fruit list information. When this button is pressed, the client that handles user interaction requests the fruit list information from the server, and the server responds with the fruit list information to the client.

What's notable here is that the client and server are independent. That is, even if the button color changes or the visual effect when clicking changes on the client side, it doesn't affect the server at all. Conversely, even if the logic for retrieving the fruit list information changes on the server, it doesn't affect the client at all.

Uniform Interface is the most important part of a RESTful system. The following 4 rules allow you to create a simple and distinct interface.

• Resource identification in requests
  Each request for a resource must be clearly distinguished. In Web Services, URI is mainly used to identify each resource.

  # Get user information
  GET /users
  
  # Modify book information
  PUT /books/:id
  

• Manipulation of resources through representations
  When the client sends a request to the server, it sends information about the request in a representation. Sending in a representation means that when the client sends a request, it determines through metadata which specific representation (JSON, XML, HTML, etc.) to receive the data in, and delivers the data in that representation.

  In other words, this means that when the client makes a request, it can send and receive data in the desired format (representation) without directly writing SQL to manipulate the database on the server.

  # Get user information
  GET /users
  Accept: application/json #Client requests to receive data as JSON
  

• Self-descriptive messages
  Each request's identification should be self-explanatory so that the server can know what function to perform just by looking at it. For example, a GET /users request tells the server to retrieve user information, and a POST /users request tells the server to create user information.

  TASK	METHOD	URI
  Search for users	GET	/users
  Delete an existing user	DELETE	/users/{user_id}
  Update an existing comment	PUT	/comments/{comment_id}
  create a comment	POST	/comments

• Hypermedia as the Engine of Application State
  The most difficult concept among the 4 rules, HATEOAS (Hypermedia as the Engine of Application State), will be explained using a web service example.

  In web services, web pages correspond to Application State. Hypermedia that represents app state in web services refers to hyperlinks. Just as hyperlinks navigate to different web pages, hypermedia represents each app state.

  In REST architecture, when the client sends a request to the server, the server includes hyperlinks for subsequent requests in its response, allowing the client to make necessary requests to the server without having to look up more API documentation.

  GET /articles
  
  HTTP/1.1 200 OK
  {
    "links": {
      "self": "http://example.com/articles",
      "next": "http://example.com/articles?page[offset]=2",
      "last": "http://example.com/articles?page[offset]=10"
    },
    "data": [
      {
        "type": "articles",
        "id": "1",
        "attributes": {
          "title": "JSON API paints my bikeshed!"
        },
        "relationships": {
          "author": {
            "links": {
              "self": "http://example.com/articles/1/relationships/author",
              "related": "http://example.com/articles/1/author"
            },
        },
        "comments": {
          "links": {
            "self": "http://example.com/articles/1/relationships/comments",
            "related": "http://example.com/articles/1/comments"
        },
        "links": {
          "self": "http://example.com/articles/1"
        }
      },
      [ ... ]
    ]
  }
  

State means not separately storing information from previous requests (sessions). To understand this, let's compare Stateful and Stateless communication:

Stateful Communication

• Client (hereafter C): Hello. What fruits do you sell here?
• Server (hereafter S): We sell red apples, green apples, bananas, and oranges. What would you like?
• C: I'll have an apple then.
• S: Sure, which apple would you like? (Remembers that an apple was ordered.)
• C: A red one.
• S: Sure, how many red apples would you like? (Remembers that a red apple was ordered.)
• C: Just 2, please.
• S: Sure, here are 2 red apples. (Remembers that a red apple was ordered and gives 2.)

Stateless Communication

• C: Hello. What fruits do you sell here?

• S: We sell red apples, green apples, bananas, and oranges. What would you like?

• C: I'll have an apple then.

• S: Sure, which apple would you like? (Doesn't remember anything.)

• C: A red one.

• S: Sure, a red what?

• C: Please give me a red apple.

• S: Sure, how many red apples would you like? (Doesn't remember anything.)

• C: Just 2, please.

• S: 2 of what?

• C: Please give me 2 red apples.

• S: Sure, here are 2 red apples.

  In the latter case, since the server doesn't remember information from the client's previous requests, the client must provide information about previous requests to the server. That's why Stateless communication seems very inefficient. But let's think about a situation where the fruit shop has many customers and multiple servers are running with Stateful communication.

Stateful Communication (with multiple servers)

• C: Hello. What fruits do you sell here?
• S1: We sell red apples, green apples, bananas, and oranges. What would you like?
• C: I'll have an apple then.
• S1: Sure, which apple would you like? (Remembers that an apple was ordered.)
• C: A red one.
• S1: Sure, how many red apples would you like? (Remembers that a red apple was ordered.)
• C: Just 2, please. (S1 has too much work, so S2 takes over the order.)
• S2: 2 of what? (Remembers that 2 were ordered.)
• C: Apples please.
• S2: Sure, which apples, 2 of them? (Remembers that 2 apples were ordered.)

Clients should be able to cache responses (storing responses in preparation for future identical requests) to improve performance. To do this, the server should indicate whether responses can be cached or not to prevent incorrect information from being cached.

While we simplify it to client and server, there can be multiple layers between the client and server. For example, there could be a Load Balancer that distributes requests when there are multiple servers, or a Security Layer that verifies the authority of the API requester. Each Layer should be separated and able to operate independently.

Just like the client and server example mentioned above, changes in the Security Layer should not affect other Layers. So the best layering is when a layer is added, other layers don't know it was added and operate the same way.

Through the conditions of REST architecture, you can:

• Build web services that can handle large-scale loads (Scalability),
• Separate servers by role to operate services (Decoupling),
• Manage APIs simply (Simplicity).

The Richardson Maturity Model is a concept created by Leonard Richardson as a model for determining how RESTful a Web API is.

Through this model, you can understand the conditions for creating a RESTful API.

The most basic level, meaning an API that is not RESTful at all. At this level, all requests are handled through a single endpoint.

URI	HTTP VERB	OPERATION
/doingWork	POST	retrieve/add customers, remove/update fruit

The first level is where URIs are distinguished by resource, but only one HTTP method is used. A resource refers to data that exists on the server. One endpoint represents one resource.

For example, in a fruit shop web service, customers and fruits can be represented as resources.

URI	HTTP VERB	OPERATION
/gettingCustomers	POST	retrieve customers
/addingCustomers	POST	add new customer
/removingFruits	POST	remove an existing fruit
/updatingFruits	POST	update information of an existing fruit

The second level is where URIs are distinguished by resource and HTTP methods like GET, POST, PUT, DELETE are used.

URI	HTTP VERB	OPERATION
/customers	GET	retrieve customers
/customers	POST	add new customer
/fruits/{id}	DELETE	remove an existing fruit
/fruits/{id}	PUT	update information of an existing fruit

The final level is where URIs are distinguished by resource, HTTP methods like GET, POST, PUT, DELETE are used, and link information is included in responses to support HATEOAS (Hypermedia as the Engine of Application State).

Request:

GET /customers/1 HTTP/1.1

Response:

HTTP/1.1 200 OK

{
    customerId: 1,
    name: "John",
    address: "Seoul",
    orders: [
        {
            orderId: 1,
            orderDate: "2020-01-01",
            href: "https://api.example.com/orders/1",
            orderItems: [
                {
                    itemId: 1,
                    itemName: "Apple",
                    quantity: 10
                },
                {
                    itemId: 2,
                    itemName: "Banana",
                    quantity: 5
                }
            ]
        },
        {
            orderId: 2,
            orderDate: "2020-01-02",
            href: "https://api.example.com/orders/2",
            orderItems: [
                {
                    itemId: 3,
                    itemName: "Orange",
                    quantity: 3
                }
            ]
        }
    ],
}

A RESTful API is an API that follows REST architecture. Therefore, there is no "official" standard for RESTful APIs. Through the Richardson Maturity Model, you can understand the conditions for creating a RESTful API, but most RESTful APIs only satisfy up to Level 2. So strictly speaking, those APIs cannot be called RESTful APIs. 👀

However, since REST architecture was also created for scalability, performance, reliability, maintainability, etc., you can understand the characteristics of the service you're developing and selectively design according to that purpose.

I hope this helped you understand RESTful APIs. Now you can have arguments with people who call RESTful APIs just REST.

Thank you for reading this long article. 🙇‍

• Using REST API Correctly
• What is API
• REpresentational State Transfer
• What are RESTful web services