Resource Hierarchy

Typically resources are organized hierarchically by context. Each collection (sub-)resource is followed by an instance (single object) sub-resource. Resources may further expose their own collections as named sub-resources, etc. Each resource and sub-resource defines its own semantics, which are explicitly documented. E.g.,

/services/{serviceId}/endpoints/{endpointId}/methods/{methodId}

HTTP methods

Resource Type Method Semantics
Collection GET Returns an array of objects belonging to the collection. The array may be filtered by request-specific criteria.
Collection POST Adds a new object to the collection. The request payload must be a single object to add. Response is the newly created object (including auto-generated data such as unique IDs, timestamps, etc.)
Collection PUT Updates an array of objects in the collection. Partial updates to individual objects are supported. The update is performed transactionally.
Collection DELETE Deletes the entire collection (transactionally).
Collection/Object HEAD Equivalent to GET but without response body.
Object GET Returns the requested object.
Object PUT Updates the specified object with request payload (a single object). Partial updates are supported.
Object DELETE Deletes the specified object.

Note: Partial update means that only the object properties explicitly included in request payload will be modified.

Response format

All resources return JSON responses. List resources return a JSON array of objects; single-object resources return single objects.

Nested objects and collections

In most resource hierarchies, objects and collections available as a sub-resource may also be retrieved, created, updated and deleted as part of the parent resource. For example, in the Service Definition hierarchy Services contain Endpoints, which in turn contain Methods. Endpoints are available separately as a sub-resource of Services; likewise Methods are available as sub-resource of Endpoints. However, it is also possible to include Endpoints (and their Methods) as part of Service objects (from the Services resource – see Field selection section below). In a similar fashion, nested objects and collections may be submitted with POST and PUT of the parent object. When updating the parent object along with its nested objects, those nested objects that are identified by their id's will be upated; new objects (without an id) will be added, and missing objects will be deleted.

Docs Navigation