Links Identification

All service calls support the links=yes parameter, which returns link data that identifies the call itself and its relationship to other services.

The links parameter provides compliance with the HATEOAS (HTML as the Engine of Application State) standard, which uses valid HTML links returned by the server to identify the current resource and to navigate from one resource to another.

Relationships

A service call typically returns a number of links, each with a relationship type that identifies how the link is related to the associated call. The following table describes the most common relationship types.

Link Type	Description
Self	Identifies the current service call.
Canonical	Identifies the preferred version of a resource call.
Child	For hierarchical resources, such as folders, this link identifies the call to access the child item or items of the resource identified in the current service call.
Parent	For hierarchical resources, such as folders, this link identifies the call to access the parent item of the resource identified in the current service call.
Prev	For service calls that include multiple pages of response data, this link identifies the call to access the previous page.
Next	For service calls that include multiple pages of response data, this link identifies the call to access the next page.

The link information returned for resource metadata includes other types of relationships, including ones that identify the type of service, such as copy, for each of the services supported for the resource. For more information, see Metadata Collection.

Example

This example shows the links portion (only) for the home folder in the response to the following service call:

GET https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1

The call requests a list of all the items in the home folder. Note that the call includes the links parameter and pagination parameters to help illustrate the available link relationships. Also note that, because the folder is the home folder, there is no link to represent the parent folder in the response.

"links": [
     {
          "rel": "self",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?links=yes&limit=2&offset=1"
     },
     {
          "rel": "canonical",
          "href": "https://www.example.com/documents/api/1.1/folders/self"
     },
     {
          "rel": "children",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items"
     },
     {
          "rel": "prev",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=0&limit=2"
     },
     {          "rel": "next",
          "href": "https://www.example.com/documents/api/1.1/folders/self/items?offset=3&limit=2"     }
],