| name | shortname | status | editor | contributors |
|---|---|---|---|---|
Endpoint Metadata Protocol |
10/EPMP |
draft |
Volodymyr Tkhir <[email protected]> |
Alexey Shmalko <[email protected]> |
The Endpoint Metadata Protocol (EPMP) is an endpoint-aware Kaa Protocol extension.
EPMP is intended to manage endpoint metadata.
Endpoint metadata contains information about the endpoint and is a collection of key-value pairs.
Examples of endpoint metadata keys: name, description, location, vendor, deviceModel, firmwareVersion, etc.
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.
The following terms and definitions are used in this RFC.
- Endpoint metadata (metadata): key-value data associated with a specific endpoint.
- Client MUST be able to retrieve the list of EP metadata keys available on the server.
- Client MUST be able to retrieve complete or partial EP metadata from the server. In case of a partial request, client SHOULD specify the metadata keys it wants to receive.
- Client MUST be able to completely or partially update EP metadata.
- Client MUST be able to delete EP metadata fields by their key names from the server.
- Server MAY restrict access for client to read and/or write to some or all EP metadata keys. In case of a client's read or write request to restricted EP metadata keys, server MUST respond with an error.
Metadata keys MUST meet the following requirements:
- non-empty strings;
- case-sensitive alphanumeric characters are permitted;
- underscore symbols are permitted;
- whitespace is not permitted.
Thus, metadata keys MUST match the following regular expression pattern: ^[a-zA-Z0-9_]+$.
The restrictions to the key format are dictated by the considerations of compatibility with various data stores and computer systems in general.
Metadata keys associated with a single endpoint MUST be unique.
Metadata field values MUST be of any JSON type.
Complete or partial endpoint metadata (set of key-value pairs) MAY be represented as a JSON object. For example:
{
"name":"Sensor 1",
"OSName":"Linux",
"OSVersion":"4.2.9",
"cores":2,
"ssd":true,
"location":{
"latitude":27.664827,
"longitude":-81.515754
},
"supportedFirmwareVersions":[
"2.0.0",
"2.0.1"
]
}where name, OSName, OSVersion, cores, ssd, location, and supportedFirmwareVersions are metadata keys.
10/EPMP follows client-initiated request/response pattern defined in 1/KP.
To retrieve the list of EP metadata keys, client MUST send requests to the following extension-specific resource path:
/<endpoint_token>/get/keys
where <endpoint_token> identifies the endpoint.
The request payload SHOULD be zero-byte empty payload. The server MUST ignore payload if any.
The server response payload MUST be a UTF-8 encoded JSON array with the the following JSON schema (0010-get-metadata-keys-response.schema.json):
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"10/EPMP get metadata keys response: a set of endpoint metadata keys",
"type":"array",
"items":{
"type":"string",
"pattern":"^[a-zA-Z0-9_]+$",
"description":"Endpoint metadata key name"
},
"uniqueItems":true
}Example:
[
"name",
"location",
"deviceModel"
]
In response, the server MUST filter out EP metadata key names to which the client does not have neither read nor write access. Some of the returned keys may only be readable or writable by the client.
To retrieve complete or partial EP metadata, client MUST send requests to the following extension-specific resource path:
/<endpoint_token>/get
where <endpoint_token> identifies the endpoint.
The request payload MUST be a UTF-8 encoded JSON object with the following JSON Schema (0010-get-metadata-request.schema.json):
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"10/EPMP get metadata request",
"type":"object",
"properties":{
"keys":{
"type":"array",
"items":{
"type":"string",
"pattern":"^[a-zA-Z0-9_]+$",
"description":"Endpoint metadata key name"
},
"uniqueItems":true,
"description":"EP metadata keys to be returned. Optional. If not specified, all EP metadata keys will be returned."
}
},
"additionalProperties":false
}Examples below.
-
Get all metadata:
{ }In its response, the server MUST filter out EP metadata keys, to which the client does not have neither read nor write access.
-
Get only
nameandlocationmetadata key-value pairs:{ "keys":[ "name", "location" ] }
Client MAY send a get metadata request with a zero-byte empty payload. In such event, server MUST process the request as if no metadata key names were specified in the request.
The server MUST NOT return the metadata keys that are not readable by the client. In case the client explicitly requests a restricted EP metadata key, the server MUST return an error.
The server response payload is a set of EP metadata key-value pairs in JSON object representation. The payload MUST be a UTF-8 encoded JSON object with the following JSON Schema (0010-get-metadata-response.schema.json):
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"10/EPMP get metadata response: a set of EP metadata key-value pairs in JSON object representation",
"type":"object",
"patternProperties":{
"^[a-zA-Z0-9_]+$":{
}
},
"additionalProperties":false
}Example:
{
"name":"Sensor 1",
"OSName":"Linux",
"OSVersion":"4.2.9"
}Completing a full metadata update request will overwrite the EP metadata on server with a new set of key-values received from client.
To update the EP metadata, client MUST send requests to the following extension-specific resource path:
/<endpoint_token>/update
where <endpoint_token> identifies the endpoint.
The request payload MUST be a UTF-8 encoded JSON object with the following JSON Schema (0010-update-metadata-request.schema.json):
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"10/EPMP update metadata request: a set of EP metadata key-value pairs in JSON object representation",
"type":"object",
"minProperties":1,
"patternProperties":{
"^[a-zA-Z0-9_]+$":{
}
},
"additionalProperties":false
}Example:
{
"deviceModel":"example model",
"name":"Sensor 1"
}The request payload is the desired new state of the EP metadata in JSON object representation. When processing a full metadata update request, the server MUST:
- create keys that were not present in the server
- update key values that were already present in the server
- remove keys that were present in the server but absent in the request payload. To avoid removing the existing key-values, use partial update operation. The server MUST NOT modify or delete the metadata keys that are not writable by the client. In case the client requests to create or update a restricted EP metadata key, the server MUST return an error.
For example, EP metadata before the update looks like this:
{
"name":"Device 1",
"description":"The first sensor",
"location":{
"latitude":27.664827,
"longitude":-81.515754
}
}The request payload:
{
"name":"Device 1",
"location":{
"latitude":27.112167,
"longitude":-81.023434
},
"vendorId":2
}As a result, value of the location key must be updated, value of the vendorId key must be added, and the description key must be deleted on the server.
A successful processing confirmation response MUST have zero-length payload.
Completing a partial metadata update request will update or create only the endpoint metadata key-value pairs present in the request payload. Compared with the full metadata update, this request does not remove the existing EP metadata keys that are not present in the request payload.
To perform a partial update of the EP metadata, client MUST send requests to the following extension-specific resource path:
/<endpoint_token>/update/keys
where <endpoint_token> identifies the endpoint.
The request payload MUST be a JSON-encoded object with the same JSON schema (http://json-schema.org/) as in full metadata update request.
Example:
{
"deviceModel":"example model",
"name":"Sensor 1"
}The server MUST NOT modify the metadata keys that are not writable by the client. In case the client requests to create or update a restricted EP metadata key, the server MUST return an error.
A successful processing confirmation response MUST have zero-length payload.
To delete EP metadata keys, client MUST send requests to the following extension-specific resource path:
/<endpoint_token>/delete/keys
where <endpoint_token> identifies the endpoint.
The request payload MUST be a UTF-8 encoded JSON object with the following JSON Schema (0010-delete-metadata-keys-request.schema.json):
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"10/EPMP delete metadata keys request",
"type":"array",
"items":{
"type":"string",
"pattern":"^[a-zA-Z0-9_]+$",
"description":"Endpoint metadata key name"
},
"minItems":1,
"uniqueItems":true
}Example:
[
"location",
"areaId"
]The server MUST NOT delete the metadata keys that are not writable by the client. In case the client requests to delete a restricted EP metadata key, the server MUST return an error.
A successful processing confirmation response MUST have zero-length payload.