Designing a Unified RESTful API: Principles, URL Naming, and Versioning

1 Overview

This document defines a unified RESTful interface design scheme intended as a reference. Although the approach is rather rigid and was not adopted in the author's previous company, it reflects the common academic recommendations found in textbooks and online resources.

1.2 Why Use REST

The goal is to decouple server and client. While SOA separates front‑end and back‑end structurally, data logic remains coupled; REST, built on HTTP, further isolates client behavior from server changes.

1.3 Document Structure

The second part explains key RESTful concepts that aid elegant API design. The third part defines URL naming conventions. The fourth part specifies message entities. The fifth part describes request methods, headers, and bodies. The sixth part details response format, including headers, status codes, and JSON bodies. The seventh part addresses version control, and the eighth part suggests implementation tools.

2 Key Concepts

2.1 RESTful

REST is not a protocol, file format, or framework; it is a collection of design constraints such as statelessness and hypermedia as the engine of application state (HATEOAS). Resources are representations of server‑stored data, and their state changes with each request.

2.2 HATEOAS

Hypermedia As The Engine Of Application State means the client interacts with the server solely through hypermedia links provided in responses, without prior knowledge of the API beyond HTTP.

2.3 Security

A method is safe if invoking it any number of times does not alter server state; otherwise it is unsafe.

2.4 Idempotency

A method is idempotent when repeated identical calls produce the same result; safety implies idempotency, but not vice‑versa.

3 URL Naming

URLs identify resources and should use nouns, e.g., /users, /users/children. Parameters can be embedded ( /users/313) or passed as query strings ( /users?name=tom&phone=123).

4 Message Entity

The entity‑body of requests and responses is a JSON string containing business‑related data.

5 Request

5.1 Methods

5.1.1 GET

Retrieves resources; parameters appear in the URL or query string. GET must be idempotent and must not modify data.

5.1.2 POST

Creates a resource; request body is JSON and Content‑Type: application/json. Successful creation returns status 201 with a Location header pointing to the new resource.

5.1.3 PUT

Updates an existing resource; must be idempotent and uses the same headers as POST.

5.1.4 DELETE

Deletes a resource; must be idempotent.

5.2 Header

Requests should set Content‑Type: application/json and include a custom version header for API versioning.

5.3 Body

The body is a JSON string whose structure is defined by the API.

6 Response

6.1 Header

Response headers depend on the status code. Some teams return 200 for all cases and encode error information in the JSON body.

6.2 Status Codes

Successful responses use 200 (or 201 for creation). Client errors such as 406 indicate request issues; server errors like 500 indicate server‑side problems.

6.3 Body

Responses use JSON with two possible structures:

{
  "error": {
    "code": xxx,
    "message": "xxx",
    "data": {...}
  }
}

Successful responses contain a result object; error responses contain an error object with a human‑readable message.

7 Version Control

API upgrades may add new endpoints, add fields, modify or delete fields, change business logic, or remove endpoints. Backward‑compatible changes (adding endpoints or fields) do not affect clients, while other changes require client updates. Servers should keep old versions available for a transition period.

8 Implementation Tools

8.1 Spring HATEOAS

Spring HATEOAS integrates easily with Spring MVC to build RESTful services. See the official documentation for details.

9 Defects

The scheme aggregates widely accepted practices but lacks details such as pagination. Compared to serverless designs that push business logic to the front‑end, this approach keeps logic on the server, simplifying the API.

10 References

No formal bibliography is provided; readers should verify sources independently.

Author: Gordon Original: https://bungder.github.io/2017/07/24/REST/