...
The following table shows how the HTTP methods are typically used to implement a Web API.
...
| Resource | GET | PUT | POST | DELETE |
|---|---|---|---|---|
| Collection URI such as http://eg.com/resources/ | List the URIs and perhaps other details of the collection's members. | Replace the entire collection with another collection. | Create a new entry in the collection. The new entry's URI is assigned automatically and is usually returned by the operation. | Delete the entire collection. |
| Element URI such as http://eg.com/resources/item7 | Retrieve a representation of the addressed member of the collection, expressed in an appropriate Internet media type. | Replace the addressed member of the collection, or if it doesn't exist, create it. | Not generally used. Treat the addressed member as a collection in its own right and create a new entry in it. | Delete the addressed member of the collection. |
...
Each URL request can contain optional query parameters. Query parameters are added to the end of the URL, following a ? character, and separated from other parameters with a & character. The following table describes the supported query parameters:
...
| Query Parameter | Applies To | Description |
|---|---|---|
| format={data_format} accept={media_types} | (all) | Allows the default data format to be overridden. See 2429391 Data Formats below for further details. |
| ref_type=(url | id) | devices, datapoints | The type of references for related objects. Default: url. See 2429391 See Depth and Reference Types below for further details. |
| depth={levels} | devices | The number of levels to expand dependent objects. Default: 0. See 2429391 Depth and Reference Types below for further details. |
| search={search_text} | (all) | Filters a collection of resources by performing a case-insensitive partial match for {search_text} against string-based fields marked as 'searchable' above. Multiple parameters may be specified. |
| {field_name}={field_value} | (all) | Filters a collection of resources by performing a case-sensitive exact match for {field_value} against the specified {field_name}. Unlike search, {field_name} typically also works with 'hidden' fields. Multiple parameters may be specified. |
| ordering=[-]{field_name} | (all) | Controls the ordering of the returned list of resources to order them based on the specified {field_name} (default: id). Specify - prefix to sort in descending order. |
| category={categories} | devices, datapoints | Filters a collection of resources by performing a case-insensitive search for {categories} against the categories field. Comma separated category values will be OR-ed together. Multiple category queries can be specified and these will be AND-ed together. Prefixing a category with - will negate its effect. An empty category value will match a resource with no categories. e.g., category=a,b, will return all objects with categories a OR b OR with no category. category=a&category=-b will return all objects with category a AND NOT b. |
| ids={id_list} | devices, datapoints | Filters a collection of resources to include only those specified by the comma-separated list of object IDs. |
| fields={field_list} | (all) | Controls the fields in the returned list of resources to include only those specified by the comma-separated list of field names. |
| after={timestamp} before={timestamp} | devices, datapoints | Filters a collection of resources to include only those objects modified after/before the specified {timestamp}. Timestamps must use the RFC 3339 / ISO 8601 format: YYYY-MM-DDTHH:MM[:ss[.uuuuuu]][TZ], e.g., 2013-10-24T20:49:05.713295Z. |
| max_age={seconds} min_age={seconds} | devices, datapoints | Filters a collection of resources to include only those objects updated within the last {seconds} seconds, or those older than {seconds} seconds. |
...