Rene CabralHome / Digitec Coding Practices / REST API
REST API Standards
-
All URL paths must be dashed and lowercase.
-
All URL parameters (POST, GET, etc) must be underscored and lowercase:
snake_case. -
All entities of the same type must have a common schema with a minimum set of properties.
-
Extra properties can be requested using the following notation:
resource-endpoint:(extra-property1, extra-property2)- Extra properties can be sub-collections, relationships etc of the main resource.
-
Updating or creating an entity should return the entity if discreet (i.e. tagging an asset will not return the tag or the asset but creating a tag will return the tag).
Standards for KD Core API
Note: __due to the nature of the bundle architecture, our resources are namespaced by design. This can lead to the acceptable consequence of having a route that is structured like namespace/resources or namespace-is-the-resource.
| HTTP | Route | Action |
|---|---|---|
POST |
/resources |
create resource, properties in json payload |
GET |
/resources |
get resource collection |
GET |
/resources?parameter={value} |
get filtered resource collection |
GET |
/resources/{id} |
get single resource |
GET |
/resources/{id}:(extra-property1) |
get single resource, requesting extra property (The extra property can be a sub resource like users:(addresses) or an extra property not included in the standard user entity like users:(change_password). Allowed extra properties must be documented in API docs.) |
DELETE |
/resources/{id} |
delete single resource |
DELETE |
/resources/{id}?parameter={value} |
delete single resource, additional parameters in GET string (for example: recursive=1) |
PATCH |
/resources/{id} |
update resource, properties in json payload |
POST |
/resources/{id}/link |
link resource to specified resource(s), in json payload [] |
POST |
/resources/{id}/unlink |
unlink resource to specified resource(s), in json payload [] |