Mastering RESTful API Design: Best Practices, URL Conventions, and Response Standards

1. RESTful Development Background and Overview

Network applications consist of front‑end and back‑end parts. With many front‑end devices (mobile, tablet, desktop, etc.) a unified mechanism is needed for communication, which has led to the popularity of API architectures and the "APIFirst" design philosophy. RESTful API is a mature theory for designing internet application APIs.

REST (Representational State Transfer) defines a set of architectural constraints. If an architecture satisfies these constraints it is called RESTful. REST does not create new technologies; it leverages existing Web standards and can theoretically be used with protocols other than HTTP, though HTTP is the most common implementation.

2. RESTful Design Style

2.1 Recommended URL Format

URL format:

http(s)://server.com/api-name/{version}/{domain}/{rest-convention}

{version} indicates the API version. {domain} can represent a technical or business area (e.g., security, a functional module). {rest-convention} denotes the set of REST endpoints under that domain.

2.2 Parameter Formats

GET requests commonly use two formats:

URL query parameters (recommended), e.g. https://www.example.com/v1.1?name='lk-abc%&age='lt-10' Path parameters, e.g. https://www.example.com/v1.1/employees/{id} POST requests can submit parameters in two common formats:

POST https://www.example.com/v1.1
Content-Type: application/json;charset=utf-8
{"title":"test","sub":[1,2,3]}

POST https://www.example.com/v1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
title=test&sub[]=1&sub[]=2&sub[]=3

2.3 Response Body Format

A typical JSON response structure:

{
  "status": 200,
  "message": "User query succeeded",
  "document": "https://www.example.com/doc#userinfo",
  "data": {
    "className": "com.fiberhome.smartas.pricecloud.User",
    "id": "1b434wtert564564sdffey32",
    "name": "lilei",
    "age": 18,
    "job": {
      "className": "com.fiberhome.smartas.pricecloud.Job",
      "id": "1b434wtert564564sdffeyey",
      "name": "Microservice Architect"
    }
  }
}

2.4 Protocol

For security, HTTPS is recommended for API communication, though HTTP can also be used.

2.5 Domain Name

Deploy APIs under a dedicated domain to hide deployment details. Multi‑level domains can be considered as the service map grows.

2.6 Versioning

Place the API version in the URL (or optionally in HTTP headers). URL versioning is more convenient and intuitive, as used by GitHub.

2.7 Plural Nouns in Paths

In RESTful design each URL represents a resource, so URLs should contain nouns (usually plural) that correspond to database table collections, never verbs.

2.8 HTTP Methods for Resource Operations

GET – retrieve resources

POST – create a new resource

PUT – replace an existing resource

DELETE – remove a resource

HEAD – fetch metadata

OPTIONS – discover allowed operations

TRACE – echo the request for testing

CONNECT – switch to a tunnel (proxy)

2.9 Filtering, Sorting, Field Selection, and Paging

Provide collection filtering, sorting, field selection, and pagination:

Filtering: GET /cars?color=red Sorting: GET /cars?sort=-manufacturer,+model Field selection: GET /cars?fields=manufacturer,model,id,color Paging: GET /cars?offset=10&limit=5 with X-Total-Count header and standard Link header for navigation.

2.10 Unified JSON Response

Standardize on JSON for platform‑wide API management and to follow the microservice principle of “wide input, narrow output”.

2.11 Status Codes

Common HTTP status codes for API responses (reference: RFC 2616):

200 OK – successful GET

201 CREATED – successful POST/PUT/PATCH

202 ACCEPTED – request queued (asynchronous)

204 NO CONTENT – successful DELETE

400 BAD REQUEST – client error

401 UNAUTHORIZED – authentication failure

403 FORBIDDEN – authorized but access denied

404 NOT FOUND – resource does not exist

406 NOT ACCEPTABLE – unsupported response format

410 GONE – resource permanently removed

422 UNPROCESSABLE ENTITY – validation error

500 INTERNAL SERVER ERROR – server failure

2.12 Hypermedia Links

RESTful APIs should provide hypermedia links in responses so clients can discover next actions without consulting documentation.

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

2.13 API Extension Considerations

Authentication, authorization, and parameter encryption can be handled via HTTP headers (tokens, trace IDs, etc.).

Separate internal and external APIs may require different designs or protocols.

Prefer stateless, idempotent operations; evaluate HTTP/2.0 for performance improvements.

Source: http://blog.csdn.net/zl1zl2zl3/article/details/73867113