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.

This section consists of the following:

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.

Resources

Resource	URI	Supported Methods	Comments
User	/api/users/	GET	Returns a list of users. Must be logged in. If logged in as an administrative user, all users will be returned, otherwise only the user that is logged in will be returned.
	/api/users/	POST	Adds a new user (must be logged in as an administrative user).
	/api/users/{id}/	GET	Returns the details of the specified user.
		PUT PATCH	Updates the details of the specified user (e.g., the email field).
		DELETE	Deletes the specified user (must be logged in as an administrative user).
Device	/api/devices/	GET	Returns a list of all devices.
	/api/devices/	PUT PATCH	Bulk updates the details of the specified list of devices. Only fields that are not marked as 'read-only' (see below) will be modified.
	/api/devices/{id}	GET	Returns the details of the specified device.
		PUT PATCH	Updates the details of the specified device (e.g., the notes field). Only fields that are not marked as 'read-only' (see below) will be modified.
		DELETE	Deletes the specified device. This should only be used on stale objects. If the device is a IzoT Network Server-based device and it is still active, it will be added back on the next update (but with a different ID).
	/api/devices/{id}/wink/	PUT	Winks (asynchronously) the specified device (if the device supports it).
	/api/devices/{id}/poll/	PUT	Polls (asynchronously) the specified device for updated information.
Datapoint	/api/datapoints/	GET	Returns a list of all datapoints.
	/api/datapoints/	PUT PATCH	Bulk updates the details of the specified list of datapoints. Only fields that are not marked as 'read-only' (see below) will be modified.
	/api/datapoints/{id}	GET	Returns the details of the specified datapoint.
		PUT PATCH	Updates the details of the specified datapoint (e.g., the value or notes fields). Only fields that are not marked as 'read-only' (see below) will be modified.
		DELETE	Deletes the specified datapoint. This should only be used on stale objects. If the datapoint is a IzoT Network Server-based datapoint and it is still active, it will be added back on the next update (but with a different ID).
	/api/devices/{device_id}/datapoints/	GET	Returns a list of only the datapoints associated with the specified device.

User Resource

Field	Format	Attributes	Description
id	integer	key, unique, read-only	The unique identifier for this user.
url	URI	read-only	The URI for this user.
username	string	max_length = 30	The username of this user.
first_name	string	max_length = 30	The first name of this user.
last_name	string	max_length = 30	The last name of this user.
email	string		The e-mail address of this user.
is_staff	boolean	read_only (see note)	Whether this user is an administrator. Note: Only an administrator can change this value.
is_active
password	string		The password for the user. Only supplied with POST, not returned by GET.

Device Resource

Field	Format	Attributes	Description
id	integer	key, unique, read-only	The unique identifier for this device.
url	URI	read-only	The URI for this device.
devid	string	max_length = 30, read-only, unique, hidden, searchable	The IzoT Network Server ID for this device.
name	string	max_length = 30, read-only, searchable	The name of this device, e.g., Lamp.
brand	string	max_length = 30, read-only, searchable	The brand of this device, e.g., Echelon.
type	string	max_length = 30, read-only, searchable	The type of this device, e.g., dimmer.
categories	string	searchable	Optional user-supplied comma-separated list of categories that can be filtered using the category parameter.
notes	string	searchable	Optional user-supplied notes for the device.
active	string	max_length = 10, read-only, searchable	The activity level of this device. One of: false, marginal, pending, or true.
datapoints	URI link / collection	read-only	Either a link or a collection of URI/ID references to the datapoints belonging to this device, depending on the value of the depth and ref_type parameters (see below).
source	string	read-only, hidden	The source (origin) of the device resource. This specifies the name of the IzoT Server collector used to collect and update information for this device. Typical examples include: lonbridge, localhost.
timestamp	timestamp	read-only	The date and time that this device was created or last modified.
hidden	boolean		Optional general-purpose flag to mark a device as hidden (default: false). Used by the dashboard web pages to selectively hide devices.

Datapoint Resource

Field	Format	Attributes	Description
id	integer	key, unique, read-only	The unique identifier for this datapoint.
url	URI	read-only	The URI for this datapoint.
name	string	max_length = 30, read-only, searchable	The name of this datapoint. For IzoT Network Server-based datapoints, these names come from the XML class files. Examples include "state", "brightness", and "power".
value	string	searchable	The current value of this datapoint. Depending on the device, some datapoints are read-only (e.g. the performance statistics on the CPU device). Writing a value to a read-only datapoint will only have a temporary effect. The value will be overwritten the next time the datapoint is automatically updated. Otherwise, writing to a datapoint will cause the value to be propagated to the device.
categories	string	searchable	Optional user-supplied comma-separated list of categories that can be filtered using the category parameter.
notes	string	searchable	Optional user-supplied notes for the datapoint.
read_only	boolean	read-only	Whether the datapoint's value field is read-only.
device	URI link	read-only	The URI reference to the device to which this datapoint belongs.
source	string	read-only, hidden	The source (origin) of the datapoint resource. This specifies the name of the IzoT Server collector used to collect and update information for this datapoint. Typical examples include: "lonbridge", "localhost".
timestamp	timestamp	read-only	The date and time that this datapoint was created or last modified.

Query Parameters

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 Data Formats below for further details.
ref_type=(url \| id)	devices, datapoints	The type of references for related objects. Default: url. See Depth and Reference Types below for further details.
depth={levels}	devices	The number of levels to expand dependent objects. Default: 0. See 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.

Data Formats

The following data formats (media types) are supported by the IzoT Server REST API:

JSON (application/json)
XML (application/xml)
API (text/html)

By default, the data format used is specified (negotiated) by the client using the standard HTTP_ACCEPT header. This default may be overridden by including either a format suffix (filetype extension), an explicit format parameter, or an accept override parameter in the URI of the request, for example:

/api/devices/.json
/api/devices/?format=json
/api/devices/?accept=application/json
/api/devices/1/.xml
/api/devices/1/?format=yaml
/api/devices/1/?accept=text/html

The trailing slash before the format specifier is required (/api/devices/1.xml will not work).

If you are accessing the API from a Web browser (that requests the text/html media type by default), you will see the browsable API format which is a developer-friendly Web page allowing simple documentation, browsing and testing of the API.

Depth and Reference Types

By default (depth=0), when retrieving resources (either a list of resources, or a specific instance), dependent (child) resource(s) are returned only by reference as a URI that must be separately retrieved to obtain the details of the dependent object(s), if any. The IzoT REST API also provides for two additional levels of automatic expansion of dependent resources. At depth=1, dependent resource(s) are expanded one level deep by returning URI(s) that point directly to the dependent resource(s). At depth=2, dependent resource(s) are fully expanded inline and returned as part of the data for the parent resource, for example:

http://izot/api/devices/5/?depth=0

{     
	"id": 5,     
	"url": "http://izot/api/devices/5/",     
	"name": "Lamp",     
	"brand": "Echelon",     
	"type": "dimmer",     
	"notes": "",     
	"active": "true",     
	"datapoints": "http://izot/api/devices/5/datapoints/",     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:04:47.120Z" 
}

http://izot/api/devices/5/?depth=1

{     
	"id": 5,     
	"url": "http://izot/api/devices/5/",     
	"name": "Lamp",     
	"brand": "Echelon",     
	"type": "dimmer",     
	"notes": "",     
	"active": "true",     
	"datapoints": [         
		"http://izot/api/datapoints/1/",         
		"http://izot/api/datapoints/2/"     
	],     
	"source": "lonbridge",     	
	"timestamp": "2013-08-12T18:04:47.120Z" 
}

http://izot/api/devices/5/?depth=2

{     
	"id": 5,     
	"url": 
	"http://izot/api/devices/5/",     
	"name": "Lamp",     
	"brand": "Echelon",     
	"type": "dimmer",     
	"notes": "",     
	"active": "true",     
	"datapoints": [         
		{             
			"id": 1,             
			"url": "http://izot/api/datapoints/1/",             
			"name": "energy_lo",             
			"value": "4051",             
			"notes": "",             
			"device": "http://izot/api/devices/5/",             
			"source": "lonbridge",             
			"timestamp": "2013-08-12T18:26:51.390Z"         
		},         
		{             
			"id": 2,             
			"url": "http://izot/api/datapoints/2/",             
			"name": "state",             
			"value": "off",             
			"notes": "",             
			"device": "http://izot/api/devices/5/",             
			"source": "lonbridge",             
			"timestamp": "2013-08-12T18:04:48.823Z"         
		}     
	],     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:04:47.120Z" 
}

This expansion does not occur for parent resources (e.g., a Datapoint's device field is never expanded in this way).

Additionally, instead of returning a URI for related resources (ref_type=url), an ID can be returned instead (ref_type=id). This applies to all related references (not just child references), but this is only used when depth=1 for list-type nested resources, for example:

http://izot/api/datapoints/1/?ref_type=url

{     
	"id": 1,     
	"url": "http://izot/api/datapoints/1/",     
	"name": "energy_lo",     
	"value": "4052",     
	"notes": "",     	
	"device": "http://izot/api/devices/5/",     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:31:52.586Z" 
}

http://izot/api/datapoints/1/?ref_type=id

{     
	"id": 1,     
	"url": "http://garyb-pi/api/datapoints/1/",     
	"name": "energy_lo",     
	"value": "4052",     
	"notes": "",     
	"device": 5,     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:31:52.586Z" 
}

http://izot/api/devices/5/?depth=1&ref_type=id

{     
	"id": 5,     
	"url": "http://izot/api/devices/5/",     
	"name": "Lamp",     
	"brand": "Echelon",     
	"type": "dimmer",     
	"notes": "",     
	"active": "true",     
	"datapoints": [         
		"1",         
		"2"     
	],     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:04:47.120Z" 
}

http://izot/api/devices/5/?depth=2&ref_type=id

{     
	"id": 5,     
	"url": "http://izot/api/devices/5/",     
	"name": "Lamp",     
	"brand": "Echelon",     
	"type": "dimmer",     
	"notes": "",     
	"active": "true",     
	"datapoints": [         
		{             
			"id": 1,             
			"url": "http://izot/api/datapoints/1/",             
			"name": "energy_lo",             
			"value": "4051",             
			"notes": "",             
			"device": "5",             
			"source": "lonbridge",             
			"timestamp": "2013-08-12T18:26:51.390Z"         
		},         
		{             
			"id": 2,             
			"url": "http://izot/api/datapoints/2/",             
			"name": "state",             
			"value": "off",             
			"notes": "",             
			"device": "5",             
			"source": "lonbridge",             
			"timestamp": "2013-08-12T18:04:48.823Z"         
		}     
	],     
	"source": "lonbridge",     
	"timestamp": "2013-08-12T18:04:47.120Z" 
}