Resource Access Protocol¶
In a LAN, our device and IoTtalk Data Gateway can known each other via Component Discovery Protocol. The device application which connects to IoTtalk always comes and go. We will consider them as kind of resource. They provide device feature (s) sometimes available and sometimes not.
In order to keep those resources well-managed, this specification will regulate the following process:
- Resource registration (creation)
- Resource deregistration (deletion)
- Resource metadata modification
- Resource metadata retrieval
| state: | Draft |
|---|
Preamble¶
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
Resource Identity¶
The basic unit of a resource is a device application. We will use UUID introduced in Component Discovery Protocol as resource identity.
The different process on same physical device MUST have different UUID. Because the feature on they may diverge.
Transportation Layer¶
The message delivered via the transportation layer MUST be constructed with two part:
- Header part
- Data part
The header part MUST indicate various protocol related metadata, including:
- The kind of process mentioned above.
- The URI endpoint for operating.
The data part is OPTIONAL and it indicate generic data container, including but can more than:
- The arguments for the process.
- Optional data field for the URI endpoint.
Implementation Suggestion¶
The RECOMMENDED transportation layer implementation is HTTP. The HTTP support is widespread, the implementation on devices will become easier.
In header part, the process can be mapped to the HTTP Verb like GET, POST, or DELETE. The HTTP URL is also easy to design. In data part, the JSON/XML content is suitable for deliver complex data structure.
Transportation Endpoint¶
The REST-like endpoint design on this protocol is RECOMMENDED.
Each endpoint has a valid set of verbs. The univeral set verbs is \(\{ \text{GET}, \text{POST}, \text{PUT}, \text{DELETE} \}\) which is inspired by HTTP verbs.
Registration Endpoint¶
This endpoint indicate the creation of a resource.
PUT /<id>
# body
<metadata>
Where <id> is the UUID of a resource
mentioned in Resource Identity.
Where <metadata> section is OPTIONAL. The device can register first, then the metadata can be added later.
Deregistration Endpoint¶
This endpoint indicate the deletion of a resource.
DELETE /<id>
Where <id> is the UUID of a resource
mentioned in Resource Identity.
Metadata Retrieval Endpoint¶
This endpoint indicates the reading of resource metadata.
GET /<id>/<field locator>
Where <id> is the UUID of a resource
mentioned in Resource Identity.
Where <field locator> is OPTIONAL.
It indicates the selector of the data field,
its format is implementation dependent.
Metadata Modification Endpoint¶
This endpoint indicates the updating of resource metadata.
POST /<id>/<field locator>
<metadata>
Where <id> is the UUID of a resource
mentioned in Resource Identity.
Where <field locator> is OPTIONAL.
It indicates the selector of the data field,
its format is implementation dependent.
Metadata¶
| accept_protos: | List of supported protocols. This field is OPTIONAL. |
||||
|---|---|---|---|---|---|
| idf_list: | idf stands for Input Device Feature. This field is OPTIONAL. It’s a list of pair (feature, units).
|
||||
| odf_list: | odf stands for Output Device Feature. This field is OPTIONAL. It’s a list of pair (feature, units).
|
||||
| name: | Arbitrary string, it can be consider as comment. |
||||
| owner: | Arbitrary string. This field is OPTIONAL. |
||||
| profile: | A JSON object for storing arbitrary data. This field is OPTIONAL. |