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

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.