Skip to main content

RESTful API Design

CDT's API follows REST principles to keep client and service decoupled and interoperable across platforms.

Core Principles​

Loose Coupling​

The client and server evolve independently. Clients do not need to know how the API is implemented internally, and the API does not need to know about its callers.

Platform Independence​

Any HTTP client can call the API regardless of platform or language.

URI Design​

Resources are the central concept. Every resource has a URI that uniquely identifies it:

https://cdt.example.com/api/buildings/1

Guidelines:

  • Use nouns, not verbs: /buildings, not /getBuildings
  • Use plural resource names: /buildings, /sites
  • Nest sub-resources where the relationship is clear: /buildings/1/files
  • Keep URIs lowercase and hyphen-separated

HTTP Methods​

MethodUse
GETRetrieve a resource or collection
POSTCreate a new resource
PATCHUpdate an existing resource (partial update)
DELETERemove a resource

Resource Representation​

Resources are represented as JSON. Responses should be consistent in shape across endpoints:

{ "id": 1, "name": "Mackenzie Building", "siteId": 4 }

Status Codes​

CodeMeaning
200 OKSuccessful GET, PATCH
201 CreatedSuccessful POST
204 No ContentSuccessful DELETE
400 Bad RequestInvalid input
401 UnauthorizedMissing or invalid auth
403 ForbiddenAuthenticated but not authorized
404 Not FoundResource does not exist
500 Internal Server ErrorUnexpected server error