Resource Types
A REST resource can be singular resource or a collection resource.
Singular Resources
A singular resource represents a single entity, such as a category or a repository. It has the following features:
- Can use a hierarchical structure that includes child resources.
- Includes a links property that supports HATEOAS, which is an important constraint of the resources. This property is used to define links to related resources.
The following table describes the properties of a link object.
Property | Description |
---|---|
rel |
Defines the relationship to the target resource. Types of links include:
|
href |
A URL for accessing the resource. |
name |
A unique identifier for the link. |
kind |
Indicates the type of target resource that the link references. Valid values are collection and item. |
Collection Resource
A collection resource represents a list of items, such as a list of categories or repositories. It has the following features:
- Extends a singular resource using the links property.
- Supports requests in parts so that you can implement a paginated response. The REST client can get a part of the collection in one request, followed by multiple subsequent requests for the next or previous part. To support this navigation, the links section can include links to the previous page and next page.
- Functions either as a root resource or a subresource.
- Includes an array of singular resources of the same type.
- Allows the client to use the orderBy command to specify an order for the items returned. Otherwise, the order can't be determined.
The following table lists querying and paging parameters for a collection resource.
Parameter | Description |
---|---|
items |
An array of items in the collection. Each item is a singular resource. |
hasMore |
A Boolean value that indicates whether there are more items to be retrieved. Valid values:
|
totalResult |
An integer value that specifies the total number of resource instances in the response. It includes the instances in the current response and the instances yet to be retrieved. |
limit |
An integer value that specifies the paging size that the server uses for a client request. The default value is 25. The server might override this value to improve application performance. |
count |
An integer value the specifies the number of items in the paging response. This value matches the value in the items parameter. |
offset |
An integer value that specifies the index of the first item to be returned. The default value is 0. For example:
|