-
Notifications
You must be signed in to change notification settings - Fork 5
Service Catalog API
Service Catalog provides a REST(ish) API to publish and discover various services (e.g., Device Catalog, MQTT Broker).
The entry point of the Service Catalog API returns a collection of Registrations in the format inspired by Hydra Collection:
{
"@context": "/static/ctx/catalog.jsonld",
"id": "/sc",
"type": "Collection",
"services": []
}
The services
array holds an array of Registrations
Each service is represented in the Service Catalog by a registration, which has the following format:
{
"id": <string>
"type": "Service",
"name": <string>,
"description": <string>,
"meta": {},
"protocols": [
{
"type": <string>,
"endpoint": {},
"methods": [],
"content-types": [ ]
}
],
"representation": { },
"ttl": <int>,
"created": <timestamp>,
"updated": <timestamp>,
"expires": <timestamp>
}
Fields created
, updated
, and expires
are generated by the Service Catalog.
The field id
needs to uniquely identify the service in the Service Catalog and the agreement is to construct it as hostname/servicename
(+ a URL prefix generated by the Service Catalog API)
The rest of the fields have following meanings:
-
name
is a short string describing a service (e.g., "MqttBroker") -
description
is a human-readable description of a service (e.g., "Demo MQTT Broker") -
meta
is any hashmap describing meta-information of a service (map[string]interface{}
) -
protocols
is an array of protocols supported by a service-
type
is a short string describing the protocol (e.g., "MQTT", "REST") -
endpoint
is an object describing the protocol endpoint (e.g., URL for a Web API) -
methods
is an array of protocol verbs (e.g., "GET,POST,PUT,DELETE" for REST, "PUB,SUB" for MQTT) -
content-types
is an array of strings representing MIME-types defined inrepresentation
-
-
representation
is a dictionary describing the MIME-types supported by a service -
ttl
is an integer defining the Time-To-Live of a service registration
A registration describing an MQTT Broker may look as follows:
{
"id": "/sc/server.example.com/MqttBroker",
"type": "Service",
"name": "MqttBroker",
"description": "Demo MQTT Broker",
"meta": {
"apiVersion": "3.1",
"serviceType": "_mqtt._tcp.server.example.com"
},
"protocols": [
{
"type": "MQTT",
"endpoint": {
"url": "tcp://server.example.com:1883"
},
"methods": [
"PUB",
"SUB"
],
"content-types": [ ]
}
],
"representation": { },
"ttl": 120,
"created": "2014-08-19T08:24:29.283372605+02:00",
"updated": "2014-08-19T09:21:19.469528757+02:00",
"expires": "2014-08-19T09:23:19.469528757+02:00"
}
Note that representation
and content-types
fields are empty, because MQTT is a wire-level protocol.
The REST(ish) API of the Service Catalog includes CRUD to create/retrieve/update/delete service registrations and a simple filtering API to search through the catalog.
-
/sc
returns all registered services as Collection - methods: GET
-
/sc/:id
returns a specific service registration given itsid
as a Registration - methods: POST (create), GET (retrieve), PUT (update), DELETE (delete)
-
:id
id of the registration
/sc/:type/:path/:op/:value
- methods: GET
-
:type
is either service (returns a random matching entry) or services (returns all matching entries) -
:path
is a dot-separated path in the Registration similar to json-path -
:op
is one of (equals, prefix, suffix, contains) string comparison operations -
:value
is the intended value/prefix/suffix/substring of the key identified by:path
curl http://catalog.example.com/sc/services/meta.serviceType/prefix/_mqtt
will return a collection of all services in the catalog which meta.serviceType
starts with _mqtt (as MQTT broker defined in the example above)
API version is included as a parameter to the MIME type of request/response:
application/ld+json;version=0.1
About Patchwork Toolkit
Configuration
- Configuring Device Gateway
- Configuring Devices
- Configuring Device Catalog
- Configuring Service Catalog
- Configuring Services
Deployment examples
- Singleall-in-on-box
- Multiple Device Gateways with optional central Device Catalog
- Using central Service Catalog
API for Application developers
Integrating devices
- TBD...
Third-party integrations