Skip to content

HTTP vs RESTful API

1 Overview

HTTP is a protocol, REST is an architectural style. HTTP is the foundation, and REST is a way to use HTTP to build APIs.

2 Defination

2.1 HTTP

  • HTTP (HyperText Transfer Protocol) is a communication protocol used for data exchange between a client (e.g., browser) and a server.
  • It defines request methods (e.g., GET, POST, PUT, DELETE), status codes (e.g., 200, 404, 500), and formats (e.g., JSON, HTML, XML).
  • HTTP itself does not enforce specific design practices for how resources or operations should be structured.

2.2 RESTful API

  • REST (Representational State Transfer) is an architectural style that leverages HTTP and focuses on the design of APIs.
  • It emphasizes resources and the proper use of HTTP methods to interact with those resources.
  • RESTful APIs are HTTP-based APIs designed in a way that aligns with REST principles.

2.3 Declarative HTTP

Declarative HTTP is a higher-level abstraction over HTTP (or RESTful APIs) where developers focus on what they want to achieve rather than how to implement it. Frameworks and libraries handle the low-level implementation details like connection setup, request construction, and response parsing.

3 Differences in design and usage

3.1 Regular HTTP APIs

3.1.1 Design Style

  • Often lacks standardization in URL structure and usage of HTTP methods.
  • URLs might include action names or operational details.

3.1.2 Request Examples

  • Fetch user info:
GET http://example.com/getUserInfo?id=123
  • Update user info:
GET http://example.com/updateUserInfo?id=123&name=Alice
  • Delete user:
GET http://example.com/deleteUser?id=123

3.1.3 Characteristics

  • URLs often contain actions (getUserInfo, updateUserInfo), making it harder to maintain consistency.
  • HTTP methods (e.g., GET, POST) are not always used correctly.
  • Developers need to understand custom naming conventions.

3.2 RESTful APIs

3.2.1 Design Style

  • Focuses on resources rather than actions. URLs represent resources, and HTTP methods define the operations.
  • Standardized and consistent.

3.2.2 Request Examples

Fetch user info:

GET http://example.com/users/123

Update user info:

PUT http://example.com/users/123
Body:
{
  "name": "Alice"
}

Delete user:

DELETE http://example.com/users/123

3.2.3 Characteristics

  • URL is clean and semantic, representing resources rather than actions.

  • HTTP methods are used correctly to perform actions (e.g., GET for read, POST for create).

  • Highly standardized, making it easier for developers to use and maintain.

3.3 Declarative HTTP

3.3.1 Design Style

  • Abstracts HTTP and RESTful API logic into simple annotations or configurations.
  • Focuses on what needs to be done, leaving the how to the framework.

3.3.2 Request Examples

Example using Feign:

@FeignClient(name = "user-service")
public interface UserServiceClient {

    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);

    @PostMapping("/users")
    void createUser(@RequestBody User user);
}

3.3.3 Characteristics

  • Highly abstracted and framework-dependent.
  • Simplifies HTTP/RESTful API interactions by handling underlying logic (e.g., headers, serialization).
  • Code is concise, focus on the business logic and don't care about the underlying implementation.
  • Commonly used in microservices and client applications.