API

Defining a specification is an important step, but the real benefits of the network will start to show once applications appear. An API should help define a common interface with which these apps can interact with the network.

Below is the outline of an API to start off the discussion. It is documented as a RESTful API, but should be implementable in any language on any platform. Feedback welcome!

---

Tracker

/tracker

• Returns a tracker document, as defined in the specification, including its things and sub-trackers.

Some trackers may contain many things, therefore a way of limiting the amount of data is required.

/tracker/things/?limit=n

• Returns a tracker document with only the first n things
• Calling this with a limit n=0 would provide a means for the tracker to return only the metadata about itself, e.g. number of items, policies, etc. This would allow downstream services to query the tracker without potentially receiving many things.

/tracker/things/?limit=n&offset=m

• Returns a tracker document with only the first n things, starting from the mth thing

/tracker/things/?since=d

• Returns a tracker document with only those things with an attribute of "updated" after the date d
• d is a date in UTC format (YYYY-MM-DDThh:mm:ssZ)
• If a thing has no "updated" attribute then the tracker may choose whether or not to return it. This could be defined as a policy of the tracker.

/tracker/things/?attribute=x

• Returns a tracker document with only those things with an attribute equalling x
• If a thing has no attribute named x then the tracker may choose whether or not to return it. This could be defined as a policy of the tracker.
• More operators could be implemented here, e.g. <, <=, etc. This would provide an alternative to the "since" parameter above.
• Multiple attributes could be chained, e.g. att1=x&att2=y, allowing for a crude querying mechanism.
• Calling this with the UUID attribute would yield exactly one thing.
• QUESTION: How to reference sub-attributes, e.g. billOfMaterials/partNumber. Would such a slash representation suffice? A truly RESTful solution would probably be to have /tracker/things/billOfMaterials/partNumber/x perhaps?

Thing

/tracker/thing/UUID

• Returns a document containing the thing identified by the UUID.
• Note: this is effectively an alias for a things query with attribute=UUID.

Sub-trackers

/tracker/trackers

• Returns a list of sub-trackers that the current tracker tracks :-)

/tracker/trackers?limit=n /tracker/trackers?limit=n&offset=m /tracker/trackers?since=d /tracker/trackers?attribute=x

• Mimics the corresponding calls to things as described above.
• There may be some differences which may be worth documenting further.

/tracker/tracker/UUID

• Returns a document containing the sub-tracker identified by the UUID.