A RESTful Web API (also called a RESTful Web Service) is a Web API implemented using the HTTP protocol and REST principles. It is a collection of resources, with four defined aspects:
- The base URI for the Web API, such as http://eg.com/resources/.
- The Internet media type of the data supported by the Web API. This is often JSON but can be any other valid Internet media type provided that it is a valid hypertext standard.
- The set of operations supported by the Web API using HTTP methods (e.g., GET, PUT, POST, or DELETE).
- The API must be hypertext driven.
...
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. |
The PUT and DELETE methods are idempotent methods. The GET method is a safe method (or nullipotent), meaning that calling it produces no side-effects.
Unlike SOAP-based Web services, there is no standard for RESTful Web APIs. This is because REST is an architectural style, unlike SOAP, which is a protocol. Even though REST is not a standard, a RESTful implementation such as the IzoT REST API can use standards like HTTP, URI, and XML.
The following sections describe the resources exposed by the IzoT REST API. By default, all operations (e.g. GET, PUT, DELETE, etc.) are only permitted when logged into an account with suitable privileges. All resources also support the OPTIONS operation which will return information on the requested resource.
...
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. |
...