Designing Robust RESTful APIs: Best Practices and Guidelines

Introduction

Network applications consist of front‑end and back‑end parts, and the proliferation of front‑end devices (mobile, tablet, desktop, etc.) requires a unified mechanism for communication, which has popularized API architectures and the "API‑First" mindset. RESTful API is a mature design theory for internet applications.

1. Protocol

Communications between API and clients should always use the HTTPS protocol.

2. Domain Name

Deploy APIs under a dedicated domain whenever possible, e.g.:

https://api.example.com

If the API is simple and unlikely to expand, it can be placed under the main domain:

https://example.org/api/

3. Versioning

Include the API version in the URL, for example:

https://api.example.com/v1/

An alternative is to place the version in HTTP headers, but URLs are more intuitive.

4. Endpoint Design

Endpoints represent resources; URLs should contain nouns (no verbs) and use plural forms that often match database table names. Example endpoints for a zoo API:

https://api.example.com/v1/zoos https://api.example.com/v1/animals https://api.example.com/v1/employees

5. HTTP Verbs

Common verbs and their SQL equivalents:

GET (SELECT): retrieve resources.

POST (CREATE): create a new resource.

PUT (UPDATE): replace a resource with a complete new representation.

PATCH (UPDATE): modify part of a resource.

DELETE (DELETE): remove a resource.

Less common verbs:

HEAD: fetch resource metadata.

OPTIONS: discover allowed operations on a resource.

6. Filtering

When result sets are large, APIs should support query parameters to filter responses, such as:

?limit=10 – limit number of records.

?offset=10 – start position.

?page=2&per_page=100 – pagination.

?sortby=name&order=asc – sorting.

?animal_type_id=1 – custom filter.

Redundant parameters are acceptable; e.g., GET /zoos/ID/animals and GET /animals?zoo_id=ID convey the same meaning.

7. Status Codes

Typical HTTP status codes used by RESTful APIs:

200 OK – successful GET.

201 CREATED – successful POST/PUT/PATCH.

202 ACCEPTED – request queued for asynchronous processing.

204 NO CONTENT – successful DELETE.

400 BAD REQUEST – client error.

401 UNAUTHORIZED – authentication required.

403 FORBIDDEN – authenticated but not allowed.

404 NOT FOUND – resource does not exist.

406 NOT ACCEPTABLE – requested format unavailable.

410 GONE – resource permanently removed.

422 UNPROCESSABLE ENTITY – validation error on create/update.

500 INTERNAL SERVER ERROR – server failure.

8. Error Handling

For 4xx responses, return a JSON object with an error key, e.g.:

{ "error": "Invalid API key" }

9. Response Formats

Standard responses per operation:

GET collection – array of resource objects.

GET single – single resource object.

POST – newly created resource object.

PUT – full updated resource object.

PATCH – updated resource object.

DELETE – empty document.

10. Hypermedia (HATEOAS)

Responses should include links to related actions, enabling clients to discover next steps without external documentation. Example root response:

{ "link": { "rel": "collection https://www.example.com/zoos", "href": "https://api.example.com/zoos", "title": "List of zoos", "type": "application/vnd.yourformat+json" } }

GitHub’s API follows this pattern, providing a list of URLs for available actions.

11. Additional Recommendations

Use OAuth 2.0 for API authentication.

Prefer JSON over XML for data exchange.