Spring Boot API design

Resource naming

Plural nouns, no verbs in the URL — the HTTP method carries the verb:

GET    /api/v1/orders          # not /api/v1/getOrders
POST   /api/v1/orders
GET    /api/v1/orders/{id}
PATCH  /api/v1/orders/{id}
DELETE /api/v1/orders/{id}

Nest only one level for genuinely owned sub-resources (/orders/{id}/items), not for every relationship — a deeply nested URL (/customers/{id}/orders/{id}/items/{id}) is usually a sign the inner resource should be its own top-level endpoint with a filter query param instead.

Versioning

Path-based versioning (/api/v1/orders) is the simplest, most-recommended approach for public REST APIs — it's visible in every request, cacheable, and requires no custom header/media-type negotiation on the client side. Spring Boot 4.1 also adds first-class API Versioning support as an alternative to hand-rolled path versioning — check spring-boot-core/references/version-baseline-4.1.md before assuming path-based versioning is the only option on a 4.1+ project. In a multi-service system, an API Gateway (see spring-boot-microservices) is often where version-based routing to different backend service versions actually happens — keep the version convention consistent between a single service's own API design and the gateway's routing rules, rather than letting the two drift independently.