Mastering RESTful API Design: Best Practices and APISIX Implementation

What Is a RESTful API

Roy Fielding defined REST (Representational State Transfer) in his 2000 doctoral dissertation, specifying six guiding constraints. A system that satisfies part or all of these constraints is loosely called RESTful.

REST Constraints

The REST architectural style emphasizes a uniform interface, statelessness, cacheability, layered system, code‑on‑demand, and client‑server separation.

RESTful API Best Practices

Designing a RESTful API revolves around a unified interface. The following practices help you create clean, maintainable APIs.

Use Nouns, Not Verbs, in Paths

Express actions with HTTP methods instead of embedding verbs in the URI.

<code>// Good
curl -X GET http://httpbin.org/orders

// Bad
curl -X GET "http://httpbin.org/getOrders"</code>

Use Plural Nouns for Collections

Represent collections with plural nouns (e.g.,

/orders

) to avoid confusion that a singular form implies a single resource.

<code>curl -X GET "http://httpbin.org/orders"   # collection
curl -X GET "http://httpbin.org/orders/1" # single item</code>

Leverage HTTP Status Codes

Standard status codes (2xx success, 3xx redirection, 4xx client error, 5xx server error) let developers quickly identify issues and reduce debugging time.

Version Management

When APIs evolve, versioning ensures existing clients continue working while new features are introduced. Common approaches include:

Path‑based versioning (e.g.,

/v1/orders

)

Query‑parameter versioning (e.g.,

/orders?version=v1

)

Header‑based versioning (e.g.,

-H "custom-version: v1"

)

<code>// Path versioning
curl http://httpbin.org/v1/orders

// Query versioning
curl http://httpbin.org/orders?version=v1

// Header versioning
curl http://httpbin.org/orders -H "custom-version: v1"</code>

How APISIX Helps with RESTful APIs

Apache APISIX is a high‑performance, cloud‑native API gateway that can run in front of any RESTful service. It provides plugins to add functionality without modifying upstream code, satisfying REST constraints such as layered system and uniform interface.

Layered System: Separate Business and Security Logic

Authentication plugins (e.g.,

key-auth

,

openid‑connect

) handle security concerns, allowing developers to focus on business logic.

Load‑Balancing Options

roundrobin

: Round‑robin with weights

chash

: Consistent hash

ewma

: Choose node with minimum latency

least_conn

: Node with lowest (active_conn+1)/weight

Custom balancer via

require("apisix.balancer.your_balancer")

Uniform Interface: Modernizing Legacy APIs

APISIX can wrap legacy endpoints to conform to RESTful conventions without changing the original service.

Proxy‑Rewrite Plugin

Rewrite request URIs to map clean RESTful paths to legacy endpoints.

<code>curl http://127.0.0.1:9080/apisix/admin/routes/1 \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {"proxy-rewrite": {"uri": "/getOrder", "scheme": "http"}},
    "upstream": {"type": "roundrobin", "nodes": {"127.0.0.1:80": 1}}
}'</code>

Response‑Rewrite Plugin

Adjust response status codes or bodies from legacy services to meet modern expectations.

<code>curl http://127.0.0.1:9080/apisix/admin/routes/1 \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{
    "methods": ["GET"],
    "uri": "/orders",
    "plugins": {"response-rewrite": {"status_code": 201, "body": "{\"code\":\"ok\",\"message\":\"new json body\"}", "vars": [["status","==",200]]}},
    "upstream": {"type": "roundrobin", "nodes": {"127.0.0.1:80": 1}}
}'</code>

Conclusion

The article covered the definition of APIs and RESTful APIs, outlined best‑practice guidelines such as noun‑based URIs, proper HTTP methods, status‑code usage, and versioning, and demonstrated how APISIX can separate business and security concerns while retrofitting legacy services to comply with RESTful principles.