- ✓Good API design follows consistent, predictable conventions that enable developers to learn the API quickly and use it correctly without constantly referring to documentation.
- ✓Resource naming in REST APIs should use nouns rather than verbs (such as /orders rather than /getOrders) and plural forms for collections, reflecting the resource-oriented philosophy of the REST architectural style.
- ✓API versioning is essential for maintaining backward compatibility when the API needs to change: common strategies include URL path versioning (/api/v1/), header versioning and query parameter versioning.
- ✓Authentication and authorisation are critical concerns in API design: OAuth 2.0 has become the standard protocol for delegated authorisation, and API keys, JWT tokens and mutual TLS are all commonly used for API authentication.
- ✓High-quality API documentation, including clear endpoint descriptions, parameter definitions, example requests and responses, error codes and authentication guidance, is as important as the API itself: a well-designed API with poor documentation will not be used effectively.
Listen to the full episode inside the course. Enrol to access all 80 episodes, plus assignments, tutor support and Student Finance funding.
Start learning →Alex: Hello and welcome back. Today we're looking at API design principles, because as Sam said last time, good API design is a genuine craft. Sam, where do the biggest design mistakes typically occur?
Sam: In two main areas. Resource modelling: if you don't think carefully about what the resources in your API represent and how they relate to each other, you end up with an inconsistent and confusing interface that's hard for developers to learn and easy to misuse. And naming: inconsistent, ambiguous or unintuitive names force developers to constantly refer to documentation rather than being able to guess correctly from context.
Alex: Let's go through the key REST design principles.
Sam: Starting with resources: a REST API should be organised around resources, the nouns of the domain, not around actions, the verbs. So an endpoint for orders should be /orders, not /getOrders or /createOrder. The HTTP method conveys the action: GET /orders retrieves orders, POST /orders creates one, PUT /orders/123 updates a specific order, DELETE /orders/123 deletes it. This separation of resource identification from action selection is central to REST.
Alex: And naming conventions?
Sam: Use consistent naming throughout. Resource names should be plural nouns: /users, /products, /orders. URL segments should be lowercase with hyphens rather than underscores or camelCase, following the convention of the web. Nested resources should reflect natural hierarchies: /users/123/orders retrieves the orders for user 123. And field names in request and response bodies should follow a consistent convention, typically camelCase in JSON.
Alex: API versioning is important for managing change over time.
Sam: Essential. Once an API is used by external consumers, you can't change it in ways that would break existing integrations without advance warning and a migration path. The most common approach is URL path versioning: /api/v1/users versus /api/v2/users. This is explicit and simple for consumers to understand. Semantic versioning principles apply: a breaking change requires a new major version, backwards-compatible additions can be made within an existing version. Maintaining multiple active versions while consumers migrate is a real operational overhead that needs to be planned for.
Alex: Authentication and authorisation are critical concerns in API design.
Sam: Absolutely. API keys are the simplest approach: a secret string that consumers include in request headers to identify themselves. They're simple to implement but have limitations around granular permission control and rotation when they're compromised. OAuth 2.0 is the standard for delegated authorisation, allowing users to grant applications access to their resources at another service without sharing their password. JWT tokens are commonly used for stateless authentication, carrying the user's identity and permissions in a digitally signed token that the API can verify without a database lookup.
Alex: Excellent practical guidance. Thanks, Sam. We'll look at building and deploying APIs next.