Location>code7788 >text

What is RESTful or GraphQL?

Popularity：335 ℃/2025-03-29 22:08:55

RESTful and GraphQL in-depth analysis

During the front-end development process, I believe everyone is familiar with Get, POST and other request methods, so it may not be very familiar with the architecture or design style of these requests. Now let me briefly introduce it here and compare it with the GraphQL architecture.

1. What is RESTful?

REST (Representational State Transfer) is an architectural style, not a specific protocol or technology. RESTful API is designed according to the REST architecture style and uses HTTP methods to perform resource operations.

1.1 Core concepts of RESTful

  1. Resource: All data is a resource, each resource is uniquely identified by a URL, and every object in the system (such as user, order) is a resource.
  2. URI（Uniform Resource Identifier）: The path that uniquely identifies the resource, such as/getUsersInfo?id=1Indicates the user with ID 1.
  3. HTTP Methods: Common methods are as follows:
    • GET: Obtain resources
    • POST: Create a resource
    • PUT/PATCH: Update resources
    • DELETE: Delete resources
  4. Statelessness: The server does not store the client's request status, and each request should contain all necessary information.
  5. Response format: JSON is usually used as the data exchange format.
  6. Uniform Interface：
    • useHTTP MethodsExpression operation
    • Resource representation form (JSON, XML, HTML)
    • HATEOAS (Hypermedia acts as an application state engine to reduce API dependencies)

1.2 The underlying principle of RESTful

The RESTful API relies on the HTTP protocol, and the underlying layer involves:

  • HTTP/1.1orHTTP/2Conduct communication.
  • Status codeReflects the operation result (such as 200 success, 404 resource does not exist, 500 server error).
  • CORS (cross-domain resource sharing)Solve cross-domain problems.
  • OAuth2、JWTIdentity authentication is achieved through other methods.

1.3 RESTful Example

1.3.1 Obtaining user information (GET request)

GET /getUsersInfo?id=1

Response example:

{
  "id": 1,
  "name": "Alice"
}

1.3.2 Create a new user (POST request)

POST /users
Content-Type: application/json

{
  "name": "Charlie"
}

Response example:

{
  "id": 3,
  "name": "Charlie"
}

1.4 Pros and cons of RESTful

advantage:

  • Comply with HTTP specifications, simple and intuitive, easy to develop and test.
  • Cache-friendly, can use the HTTP caching mechanism to improve performance.
  • Good separation, the front and back ends are separated clearly.
  • Applicable toResource-orientedapplications such as CRUD operations.
  • Server sideStateless, easy to expand.

shortcoming:

  • Requested data may be redundant,For example/usersIt may return all user data, even if the front-end only needs itname。
  • Difficult to deal with complex inquiries, multiple endpoints need to be defined, such as/users?name=Alice&age=25。
  • Complex version management, requires maintenance/v1/users，/v2/userswait.
  • May causeOver-fetching (too much data)orUnder-fetching (insufficient data)。
  • Multiple requestsOnly by obtaining complex data (such as obtaining users and their orders, two requests are required).

2. What is GraphQL?

GraphQL was open sourced by Facebook in 2015Query Language, provides a flexible API query language that allows clients to request required data accurately, rather than being limited to fixed RESTful endpoints.

2.1 Core concepts of GraphQL

  1. Schema (Mode): Use Schema to define the data structure of the API, for exampleUsertype.
  2. Query: The client can conduct flexible data query as needed to obtain data requests, such asquery { user(id: 1) { name } }。
  3. Mutation (change): Request to modify data, such asmutation { createUser(name: "Charlie") { id name } }。
  4. Resolver (parser): Backend logic, which determines how to obtain or modify data.
  5. Single Endpoint: All queries passPOST /graphqlProceed, different from multiple endpoints of RESTful.
  6. Subscription (real-time update): Supports WebSocket for real-time data push.

2.2 The underlying principle of GraphQL

GraphQL execution involves:

  • AST (Abstract Syntax Tree) Analysis: The request is parsed into AST for parsing and verification.
  • Resolver parser: Execute query logic according to Schema.
  • Data Fetching: Get data from a database, REST API, or other data source.

2.3 GraphQL Example

2.3.1 Query user list

query {
  users {
    id
    name
  }
}

Response example:

{
  "data": {
    "users": [
      { "id": 1, "name": "Alice" },
      { "id": 2, "name": "Bob" }
    ]
  }
}

2.3.2 Get a single user

query {
  user(id: 1) {
    name
  }
}

Response example:

{
  "data": {
    "user": { "name": "Alice" }
  }
}

2.3.3 Create a user (Mutation)

mutation {
  createUser(name: "Charlie") {
    id
    name
  }
}

Response example:

{
  "data": {
    "createUser": { "id": 3, "name": "Charlie" }
  }
}

2.4 Pros and cons of GraphQL

advantage:

  • Accurately obtain the required data, avoid redundant data from the RESTful API.
  • Single endpoint (/graphql), no need for multiple API paths.
  • Combinable query, the front-end can freely decide the request structure.

shortcoming:

  • High learning cost, you need to master Schema, Query, Mutation.
  • Complex caching mechanism, cannot directly utilize HTTP cache.
  • Performance issues, complex queries may cause excessive database pressure.

3. RESTful vs GraphQL comparison

characteristic RESTful API GraphQL API
Resource Endpoint Multiple endpoints (e.g./users, /posts） Single endpoint (/graphql）
Data acquisition method The server decides to return the data The client decides to return the field
Data redundancy Too many fields may be returned Return only the requested fields
Request efficiency Multiple requests to obtain complete data All required data can be obtained in a single request
Complex query Rely on multiple endpoints and query parameters Define directly in the Query statement
HTTP Cache Available for browser and CDN cache Need to customize the cache policy
Ease of use Easy to understand Need to learn Schema and query syntax
performance Suitable for simple APIs Complex queries may affect database performance

4. When to choose RESTful vs GraphQL?

  • Select RESTful API：

    • The API structure is stable and the data does not change frequently.
    • It is necessary to optimize performance with HTTP cache.
    • Suitable for public APIs such as GitHub REST API.

  • Select GraphQL：

    • The front-end needs to freely select the data field.
    • Multiple data sources (such as merged databases and third-party APIs) need to be integrated.
    • Suitable for social media, data-driven applications, such as Facebook, Twitter.

5. Summary

​ Choose RESTful: Just like ordering a set meal at a restaurant, it is simple and direct, and the chef has prepared it for you (the data format is fixed), which is suitable for most ordinary needs. Advantages: Fast development and easy maintenance, and can be understood by novices. ​ Disadvantages: If you want to order more and less food (adjust the data), you have to ask the chef to change the menu (change the interface).

Choose GraphQL: Like eating a self-service spicy hotpot, pick up the dishes by yourself (the front end can get the data as needed). Advantages: Flexible and easy-to-use (avoid multiple requests), and the backend does not need to change the interface frequently. Disadvantages: The seasoning table is too complicated (the learning cost is high), and eating too much is easy to hold on (the performance optimization is difficult).

Simply put: use REST for small projects and simple requirements (saving worry); use GraphQL for complex systems and front-end changes every day (saving trouble).

<Previous Next>