Principles of API Design: Frontend-Backend Communication ProtocolsPrinciples of API Design: Frontend-Backend Communication Protocols

------

0. First, a Question: Have You Experienced These Nightmares0. First, a Question: Have You Experienced These Nightmares

Scenario 1: Inconsistent API NamingScenario 1: Inconsistent API Naming

GET /getUserData GET /fetchUserInfo GET /queryUserById GET /users/query

Four endpoints, same functionality, completely different naming styles. New hires are confused: which one should I use?Four endpoints, same functionality, completely different naming styles. New hires are confused: which one should I use?

Scenario 2: Inconsistent Error HandlingScenario 2: Inconsistent Error Handling

// Some return HTTP status codes HTTP/1.1 404 Not Found // Some return 200 + code HTTP/1.1 200 OK { "code": 404, "message": "User not found" } // Some just throw exceptions HTTP/1.1 200 OK { "error": "Something went wrong" }

The frontend doesn't know how to determine if a request was successful.The frontend doesn't know how to determine if a request was successful.

Scenario 3: Inconsistent Response StructuresScenario 3: Inconsistent Response Structures

// Endpoint A { "data": { ... } } // Endpoint B { "result": { ... } } // Endpoint C { "content": { ... } }

Every endpoint returns a different format, requiring the frontend to handle each one individually.Every endpoint returns a different format, requiring the frontend to handle each one individually.

------

Good API design is like a restaurant's ordering system — clear menu, standardized procedures, and informative error messages.Good API design is like a restaurant's ordering system — clear menu, standardized procedures, and informative error messages.

------

1. Overview of an API1. Overview of an API

API (Application Programming Interface) is simply the "agreement for communication between programs."API (Application Programming Interface) is simply the "agreement for communication between programs."

1.1 Restaurant Analogy1.1 Restaurant Analogy

1.2 A Complete API Request1.2 A Complete API Request

👇 Try it out: Click the button below to observe a complete API request-response flow:👇 Try it out: Click the button below to observe a complete API request-response flow:

------

2. API Design Philosophy: RPC / REST / GraphQL / gRPC2. API Design Philosophy: RPC / REST / GraphQL / gRPC

Before diving into specific RESTful design, let's understand four major API design styles:Before diving into specific RESTful design, let's understand four major API design styles:

2.1 REST vs RESTful: What's the Difference2.1 REST vs RESTful: What's the Difference

Many people confuse these two concepts:Many people confuse these two concepts:

Analogy:Analogy:

• REST is like "minimalism" — a design philosophyREST is like "minimalism" — a design philosophy
• RESTful API is like "a minimalist room" — a concrete implementation of that philosophyRESTful API is like "a minimalist room" — a concrete implementation of that philosophy

Six REST Constraints:Six REST Constraints:

------

3. RESTful Design: Making URLs Communicate3. RESTful Design: Making URLs Communicate

REST (Representational State Transfer) is an architectural style with core principles:REST (Representational State Transfer) is an architectural style with core principles:

• Abstract things on the network as "Resources"Abstract things on the network as "Resources"
• Use URLs to identify resourcesUse URLs to identify resources
• Use HTTP methods to operate on resourcesUse HTTP methods to operate on resources

3.1 Warehouse Analogy3.1 Warehouse Analogy

Key Principle: URLs are nouns, not verbs.Key Principle: URLs are nouns, not verbs.

3.2 URL Design Rules3.2 URL Design Rules

3.3 HTTP Method Selection3.3 HTTP Method Selection

------

4. Status Codes: Making Errors "Communicate"4. Status Codes: Making Errors "Communicate"

HTTP status codes are the standard way for servers to tell clients "what happened."HTTP status codes are the standard way for servers to tell clients "what happened."

4.1 Status Code Categories4.1 Status Code Categories

4.2 Common Status Code Demo4.2 Common Status Code Demo

👇 Try it out: Click the button below to learn about common status codes:👇 Try it out: Click the button below to learn about common status codes:

------

5. Error Handling: Graceful "Rejection"5. Error Handling: Graceful "Rejection"

Good error handling lets clients "understand what happened from the status code" instead of guessing.Good error handling lets clients "understand what happened from the status code" instead of guessing.

4.1 Error Handling "Pitfall Guide"4.1 Error Handling "Pitfall Guide"

Pitfall 1: Returning 200 for All ErrorsPitfall 1: Returning 200 for All Errors

// ❌ Bad practice HTTP/1.1 200 OK { "error": "Something went wrong" }

Problem: Caching layers will cache this "successful" response, and monitoring systems won't detect the issue.Problem: Caching layers will cache this "successful" response, and monitoring systems won't detect the issue.

Pitfall 2: Error Messages Too VaguePitfall 2: Error Messages Too Vague

// ❌ Bad practice HTTP/1.1 400 Bad Request { "message": "Invalid parameters" }

Problem: The client doesn't know which parameter is wrong or why.Problem: The client doesn't know which parameter is wrong or why.

Pitfall 3: Exposing Sensitive InformationPitfall 3: Exposing Sensitive Information

// ❌ Dangerous practice HTTP/1.1 500 Internal Server Error { "stack": "at UserService.login...", "sql": "SELECT * FROM..." }

Danger: Exposes code structure and database queries that attackers can exploit.Danger: Exposes code structure and database queries that attackers can exploit.

5.2 Correct Error Handling Demo5.2 Correct Error Handling Demo

👇 Try it out: Compare "good" and "bad" error response designs:👇 Try it out: Compare "good" and "bad" error response designs:

------

6. Versioning: API "Backward Compatibility"6. Versioning: API "Backward Compatibility"

6.1 Motivation for Versioninging6.1 Motivation for Versioninging

Scenario: Your app has 1 million users, and you need to modify the order endpoint.Scenario: Your app has 1 million users, and you need to modify the order endpoint.

Without versioning:Without versioning:

• New app calls new endpoint → works fineNew app calls new endpoint → works fine
• Old app calls new endpoint → missing fields, crashes!Old app calls new endpoint → missing fields, crashes!

Correct approach:Correct approach:

• /v1/orders - Old endpoint, continues serving old apps/v1/orders - Old endpoint, continues serving old apps
• /v2/orders - New endpoint, new features go here/v2/orders - New endpoint, new features go here

6.2 Versioning Strategies6.2 Versioning Strategies

6.3 Version Evolution Example6.3 Version Evolution Example

Using the user endpoint as an example, showing v1 to v2 evolution:Using the user endpoint as an example, showing v1 to v2 evolution:

------

7. Response Structure Design7. Response Structure Design

Response structure is the "data contract" for frontend-backend collaboration. A unified format dramatically reduces communication costs.Response structure is the "data contract" for frontend-backend collaboration. A unified format dramatically reduces communication costs.

7.1 Industry Best Practices7.1 Industry Best Practices

7.2 Best Practices Summary7.2 Best Practices Summary

Combining the above specifications, response structure design should follow these principles:Combining the above specifications, response structure design should follow these principles:

1. Consistency First: All endpoints use the same response structure; the frontend can build a unified request layerConsistency First: All endpoints use the same response structure; the frontend can build a unified request layer
2. Machine-Readable: Error codes + error reasons allow programs to handle errors automaticallyMachine-Readable: Error codes + error reasons allow programs to handle errors automatically
3. Human-Friendly: Clear message descriptions including resolution suggestionsHuman-Friendly: Clear message descriptions including resolution suggestions
4. Traceable: request_id spans the entire request chain for easy issue identificationTraceable: request_id spans the entire request chain for easy issue identification
5. Internationalization Support: Extend localized messages through detailsInternationalization Support: Extend localized messages through details

7.3 Data Field Design Standards7.3 Data Field Design Standards

data is the core of the response, and its design directly impacts frontend development efficiency.data is the core of the response, and its design directly impacts frontend development efficiency.

7.4 Advanced Error Response Design7.4 Advanced Error Response Design

💡 Tips Praktis💡 Pro Tip

- [Google API Design Guide - Errors](https://cloud.google.com/apis/design/errors) - [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines) - [Alibaba Java Development Manual](https://developer.aliyun.com/special/tech-java) - [Heroku HTTP API Design Guide](https://github.com/interagent/http-api-design) - [Stripe API - Errors](https://docs.stripe.com/api/errors) - [JSON:API Specification](https://jsonapi.org/format/)- [Google API Design Guide - Errors](https://cloud.google.com/apis/design/errors) - [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines) - [Alibaba Java Development Manual](https://developer.aliyun.com/special/tech-java) - [Heroku HTTP API Design Guide](https://github.com/interagent/http-api-design) - [Stripe API - Errors](https://docs.stripe.com/api/errors) - [JSON:API Specification](https://jsonapi.org/format/)

------

8. Practice: E-commerce System API Design Example8. Practice: E-commerce System API Design Example

CODE 📋 Salin📋 Copy

# User Module GET /v1/users # Get user list POST /v1/users # Create new user GET /v1/users/{id} # Get user details PUT /v1/users/{id} # Full update user PATCH /v1/users/{id} # Partial update user DELETE /v1/users/{id} # Delete user # Order Module GET /v1/users/{id}/orders # Get orders for a user POST /v1/orders # Create order GET /v1/orders/{id} # Get order details PATCH /v1/orders/{id}/status # Update order status # Product Module (use query params for complex filtering) GET /v1/products?category=phone&price_max=5000&sort=price_desc&page=1

------

9. Using AI to Assist API Design9. Using AI to Assist API Design

AI can help you quickly generate specification-compliant API designs. The key is providing clear context and constraints.AI can help you quickly generate specification-compliant API designs. The key is providing clear context and constraints.

9.1 Prompt Template9.1 Prompt Template

CODE 📋 Salin📋 Copy

You are a senior backend architect, proficient in RESTful API design. Please help me design a set of API endpoints. ## Business Background [Describe your business scenario, e.g., e-commerce system, blog platform, task management, etc.] ## Functional Requirements [List the required functional modules, e.g.: - User management: registration, login, personal information - Order management: create order, query orders, cancel order - Product management: product list, product details, search] ## Design Requirements 1. Follow RESTful conventions 2. URLs use plural nouns, lowercase + hyphens 3. Use HTTP methods correctly (GET/POST/PUT/PATCH/DELETE) 4. Unified response format: { code, message, data, request_id } 5. Appropriate status code usage 6. Versioning: URL path approach (/v1/) ## Output Format Please output in the following format: ### Endpoint List | Method | URL | Description | Request Body | Response Body | |--------|-----|-------------|--------------|---------------| ### Request/Response Examples [Detailed examples for key endpoints] ### Status Code Descriptions [Status codes used and their meanings]

9.2 Practical Example: E-commerce Order API9.2 Practical Example: E-commerce Order API

Input Prompt:Input Prompt:

CODE 📋 Salin📋 Copy

You are a senior backend architect, proficient in RESTful API design. Please help me design a set of API endpoints for an e-commerce order system. ## Business Background A B2C e-commerce platform where users can browse products, place orders, and view order status. ## Functional Requirements - Order module: create order, query order list, query order details, cancel order, pay order - Cart module: add product, modify quantity, remove product, view cart ## Design Requirements 1. Follow RESTful conventions 2. URLs use plural nouns, lowercase + hyphens 3. Use HTTP methods correctly 4. Unified response format 5. Versioning: /v1/

AI Output Example:AI Output Example:

Method	URL	Description
POST	/v1/orders	Create order
GET	/v1/orders	Query order list
GET	/v1/orders/{id}	Query order details
PATCH	/v1/orders/{id}/status	Update order status (cancel/pay)
GET	/v1/users/{id}/cart	Get cart
POST	/v1/users/{id}/cart/items	Add product to cart
PATCH	/v1/users/{id}/cart/items/{itemId}	Modify cart item quantity
DELETE	/v1/users/{id}/cart/items/{itemId}	Remove cart item

9.3 Notes on AI-Assisted Design9.3 Notes on AI-Assisted Design

Note	Description
Provide complete context	Business background, user roles, and data relationships should all be clearly stated
Define constraints clearly	Naming conventions, versioning strategy, and response format should be defined upfront
Iterate and refine	The first output may not be perfect; ask follow-up questions and request modifications
Manual review	AI-generated content needs human verification against business requirements
Cover edge cases	Ask AI to consider error handling, permission control, pagination, and other edge cases

💡 Tips Praktis💡 Pro Tip

- "Please add error response examples for each endpoint" - "Please consider pagination, sorting, and filtering parameters" - "Please add permission control descriptions for the endpoints" - "Please check if it follows RESTful best practices"- "Please add error response examples for each endpoint" - "Please consider pagination, sorting, and filtering parameters" - "Please add permission control descriptions for the endpoints" - "Please check if it follows RESTful best practices"

------

GlossaryGlossary

Term	English	Explanation
API	Application Programming Interface	Agreement for communication between programs
REST	Representational State Transfer	An architectural style that uses URLs to identify resources
Resource	Resource	Core concept in REST architecture, has unique identifiers (URLs)
Idempotency	Idempotency	Multiple executions produce the same result
Status Code	Status Code	Response status defined by the HTTP protocol
Versioning	Versioning	Allows old and new APIs to coexist for smooth upgrades
Request Body	Request Body	Data carried by POST/PUT/PATCH requests
Response Body	Response Body	Data returned by the server
Header	Header	Metadata for requests/responses (e.g., Content-Type)
Authentication	Authentication	Verifying "who you are" (login, Token)
Authorization	Authorization	Verifying "what you can do" (permissions)

← SebelumnyaPrevious3-browser-and-frontend/web-performance3-browser-and-frontend/web-performance SelanjutnyaNext →4-server-and-backend/api-intro4-server-and-backend/api-intro