Home / 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

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-are-the-resources.

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 array in json payload (an array of one or more)
POST	/resources/{id}/unlink	unlink resource to specified resource(s), in array in json payload (an array of one or more)