Principles of Web API design

Designing a web service API is about structuring a system that is predictable, consistent, and maintainable for its consumers. Whether it’s a RESTful API, GraphQL, or something custom, good design matters far more than which web framework or backend language you use.

Use resource-oriented URIs

Web APIs should expose resources using URIs that are nouns, not verbs.

Here’s a good example:

GET /users/123
POST /orders
PATCH /products/456

Here’s a bad example:

GET /getUser?id=123
POST /createOrder
PATCH /updateProduct/456

Why?

• Resource URIs follow REST principles.
• HTTP verbs already describe the action, so don’t duplicate it in the path.

HTTP methods semantics

HTTP methods and how they should be used in a web service are summarized in Table 10.2:

Verb

Action

Use...