4.6 List resources

‌4.6 List resources‌

4.6.1 Introduction

Many resources within this standard are derived from the <List> object. Throughout this standard, these resources will collectively be referred to as list resources.

The following attributes are defined for list resources:

 all is used to indicate the total number of items (subordinate resources) that exist in the list resource. This number may vary according to the client’s access privileges.

 results is used to indicate the number of items (subordinate resources) included in a specific subset of the list (result from a paged GET query to the list, etc.). This value will always be less than or equal to “all.”

Clients and servers use these attributes, combined with the query string parameters described below, to implement paged access to lists. Client control of list paging is important for resource-constrained devices.

List items (subordinate resources) are read using one of the two idioms described below:

1) Ordinal access to the first, second, nth, etc. item in the list is supported via query string parameters included with a GET to the list resource URI.

2) Random access to specific list items is supported via a GET directly to the URI of the list item.

Some list items may be created by POSTing a list item representation to the URI of the list (e.g., Notifications), while others may be created using private interfaces over the provider network. Ordinal placement of the new resource within the list is determined by the list sort order (defined by each list).

Each function set defined in this standard that contains list resources includes a list ordering table. Each list resource has an entry in the corresponding table that describes the details of one or more unique sort keys and the precedence of those keys. A list resource’s elements SHALL be ordered according to this specified list ordering.

4.6.2 Query string parameters

Query string parameters are parameters added to a URI to provide filtering/paging of list items returned in query results.

The list paging mechanism allows GET requests to specify the range of list items to be returned in a query result set. The general syntax of a paged query is as follows:

{URI}?s={x}&a={y}&1={z}

Where {URI} represents a URI used to address a list resource, (s | a | 1) represent query string parameters (further defined below), and {x}, {y}, and {z} represent the respective query string parameter values.

The query string parameters are defined as:

 s (“start”) is used to indicate the first ordinal position in the list to be returned in the query result list as determined by the list’s ordering. The value is specified in decimal. The first ordinal position of the list SHALL be designated with a value of “0” and the maximum possible value is “4294967295.” If this query string parameter is not specified, the default start value SHALL be “0.”

 a (“after”) is used to indicate that only items whose primary key occurs after the given date/time parameter should be included in the query result list. This query string parameter is only applied to list resources that are ordered using a time-based primary key. The parameter SHALL be ignored if the primary key is not time-based. The format of the parameter SHALL be a 64-bit decimal number with identical semantics as that of the TimeType (see subclause 12.2 and the XML XSD in the supplemental material of IEEE Std 2030.5).

 l (“limit”) is used to set the maximum number of list items (up to 4 294 967 295) to be included in the query result list. The value is specified in decimal. If this query string parameter is not specified, the default limit SHALL be “1.” Servers MAY return a result list smaller than that specified by the client-provided limit.

If both a “start” and “after” query string parameter are used simultaneously, the “after” query string parameter SHALL have precedence. The “start” position 0 SHALL be relative to the position specified by the “after” parameter.

If a query string requests a List element that does not exist (e.g., s=3 when there are two items in the list), servers SHALL return an empty list representation.

Readers should note that the “after” query string parameter SHOULD NOT be used alone for paging through a list. As some list resources MAY contain multiple subordinate resources with the same time- based primary key, it is RECOMMENDED that clients wishing to paginate a list resource while using the “after” query string parameter should keep the value for the “after” query string parameter constant while changing the “start” query string parameter.

If a particular query string parameter appears more than once, then the first occurrence of the query string parameter SHALL be used (in left-to-right order) and subsequent occurrences MUST be ignored.

Server receipt of a query parameter unknown to the server MUST be ignored by the server and MUST NOT generate an HTTP error. Servers MUST NOT generate resource representations containing href attributes that contain query parameters. Clients MUST ignore query parameters contained in resource hrefs, but SHOULD NOT remove them if the URI is used for subsequent RESTful exchanges.

Should an empty list representation be requested (either through the use of query string parameters such as l=0 or when the list itself is empty), the server SHALL return no subordinate representations, but SHALL return any other elements that may be defined for the list.

Clients MUST NOT assume any index semantics for list URIs. For example, a client desiring to read the third item from the list at http://some-host/somelist MUST NOT assume a GET to http://some- host/somelist/2 will return the third item. The correct access is supported by the client issuing a GET to http://some-host/somelist?s=2&l=1 .

The following examples demonstrate the use of query string parameters with a list resource. Consider the MyTypeList resource, depicted below:

</MyType>

</MyType>

</MyType>

</MyType>

</MyType>

</MyType>

</MyType>

</MyTypeList>

This list is sorted in ascending order per the <timeStamp/> element of MyType. A GET to http://host1/the/list?s=0&l=1 will return:

</MyType>

</MyTypeList>

A GET to http://host1/the/list?s=0&l=5 will return:

</MyType>

</MyType>

</MyType>

</MyType>

</MyType>

</MyTypeList>

A GET to http://host1/the/list?s=5&l=1 will return:

</MyType>

</MyTypeList>

A GET to http://host1/the/list?s=5&l=5 will return:

</MyType>

</MyType>

</MyTypeList>

A GET to http://host1/the/list?s=12&l=2 will return a list representation containing zero items:

</MyTypeList>

or <MyTypeList href="http://host1/the/list" all="7" results="0" />

A GET to http://host6/instance/of/type/white will return:

</MyType>

A GET to http://host1/the/list?a=400&l=4 will return:

</MyType>

</MyType>

</MyType>

</MyTypeList>

A GET to http://host1/the/list?a=400&s=0&l=2 will return:

</MyType>

</MyType>

</MyTypeList>

A GET to http://host1/the/list?a=400&s=2&l=2 will return:

</MyType>

</MyTypeList>

< 上一个 | 内容 | 下一个 >