REST Resource Types

Let's discuss the two types of REST resources: a single entity, known as a singular resource, and a combined list of items, known as a collection resource.

Singular Resources

A singular resource represents a single entity, such as an employee or a purchase order, and can:

  • Use a hierarchical structure that includes child resources.
  • Include a links property that supports Hypermedia as the Engine of Application State (HATEOAS), which is an important feature of resources that's used to define links to related resources.

The following table describes the properties of a link object.

Property Description
rel Defines the relationship of a link object to the target resource. The types of links include the following:
  • rel="self": Identifies the link context in the response.
  • rel="canonical": Provides the preferred version of the resource URL.
  • rel="child": Provides a link to a child resource.
  • rel="lov": Provides a link to a resource that contains the list of values used to set a field value.
  • rel="parent": Provides a link back to the parent resource.
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.

Note:

If the description of an LOV defined for any resource says it's unsupported, then it's recommended that you don't use the LOV. You can review the LOV descriptions in the Tasks section under Request > Relationships > <LOV name>.

Collection Resources

A collection resource represents a list of items, such as a list of employees or purchase orders. A collection resource can:

  • Extend a singular resource using the links property.
  • Support 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 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.
  • Function either as a root resource or as a subresource.
  • Include an array of singular resources of the same type.
  • Allow 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 the querying and paging parameters for a collection resource.

Parameter Description
items

An array of records in a collection. Each item or record is a singular resource.

hasMore A Boolean value that indicates whether there are more items to be retrieved. The valid values are:
  • True - more values to retrieve
  • False - no more values to retrieve
totalResults

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 that 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:

  • If offset=0, the response contains all the items, starting from the first item in the collection.
  • If offset=10 and count=20, the response contains resources from 11 to 30.

To learn more, see Manage Collections.