"Items" collection
URI template supplied by the ttzn:items link in the entry point resource
The "items" collection models the entire set of news items available to the authenticated user. To make it possible to request only a subset of the collection, it is identified by a URI template [RFC6570] with the following parameters.
| Parameter | Type | Mode | Description |
|---|---|---|---|
from |
YYYY-MM-DD |
Optional | Only include items posted after this date (inclusive) |
id |
Comma-separated list of integers | Optional | Only include items with these specific IDs |
label |
Integer | Optional | Only include items from subscriptions tagged with this label |
limit |
Integer | Optional | Impose a limit on the number of items Note 1: The server may impose a lower limit Note 2: limit and page are only limiting the returned representation of the resource, and will be ignored for updating purposes |
page |
Integer | Optional Default: 1 |
Skip the first items Note: limit and page are only limiting the returned representation of the resource, and will be ignored for updating purposes |
sort |
One of oldest-first or newest-first |
Optional Default: oldest-first |
Specify a sort order |
state |
One of queued, new or archived |
Optional | Only include items with a specific reading state |
subscription |
Integer | Optional | Only include items from this subscription |
to |
YYYY-MM-DD |
Optional | Only include items posted before this date (inclusive) |
Apart from being built from the template, specific URIs can also be obtained from the standard links [RFC5988] (such as self or next) in already obtained "items" representations.
The resource itself is represented by an application/hal+json [draft] object with the following structure.
| Property | Type | Mode | Description |
|---|---|---|---|
itemCount |
{"queued":integer "new":integer "archived":integer "total":integer } |
Read-only | The number of items currently in the requested subset, per reading state Note: For the purposes of these counts, the limit, offset and state parameters are ignored, and it is not limited to the number actually embedded in this representation |
| Relation | Type | Description |
|---|---|---|
ttzn:item |
Array of "item" resources | Representations of news items |
| Relation | Description |
|---|---|
curies |
A URI template [RFC6570] for expanding rel names with the ttzn prefix into the actual documentation URIs |
first |
The URI of the first set of items in the given order Note: This is not supplied if the subset starts from the top |
last |
The URI of the last set of items in the given order Note: This is not supplied if the subset ends at the bottom |
next |
The URI of the set of items immediately following this one in the given order Note: This is not supplied if the subset ends at the bottom |
prev |
The URI of the set of items immediately preceding this one in the given order Note: This is not supplied if the subset starts from the top |
self |
The URI of the set of items contained within this representation Note: This may differ from the request URI, for instance by supplying the lower limit parameter actually used due to server-side limits |