Service Catalog API

Overview

Service Catalog provides a REST(ish) API to publish and discover various services (e.g., Device Catalog, MQTT Broker).

Data Format

ServiceCatalog

The entry point of the Service Catalog API returns a collection of Services in the following format:

    {
      "id": "<string>",
      "type": "ServiceCatalog",
      "@context": "<string>",
      "services": []
    }

The id field is used throughout the API and describes the location (relative URL) of the returned resource, fulfilling the indentifiability REST interface constraint. For entry point, it equals to the path in the API endpoint URL, which is configurable and defaults to /sc.

The fields type, and @context are used to enable LinkedData support and can be ignored by clients using the plain JSON API described in this document.

The services array holds an array of Services

Service

Each service is represented in 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>
	}

The id field is a relative URL providing a dereferenceable identifier of the service in the catalog. It is constructed as /path/ + service-id, where:

• path is the path in the catalog API endpoint URL
• service-id is a unique service identifier in the network and the convention is to construct it as hostname/servicename

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
• 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 in representation
• 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
• created, updated, and expires are generated by the Device Catalog and describe TTL-related timestamps
• page, per_page and total are used for pagination

Protocols

Services can be exposed through different protocols, and below are conventions for describing some of them (format of entries in the protocols array).

MQTT

• type: MQTT
• endpoint: {"url": "scheme://address:port", "topic": "/topic"}
• url describes the broker connection information as a URL (RFC 3986) using the following URI scheme
• topic is an optional field describing the topic used by the service. If the described service itself is an MQTT broker, can be omitted
• additional fields can be defined
• methods: ["PUB", "SUB"] - array of supported MQTT messaging directions. If the described service itself is an MQTT broker, this indicates whether it supports subscription, publishing, or both.
• PUB - indicates that the service publishes data via MQTT
• SUB - indicates that the service subscribes to data via MQTT
• content-types: ["application/json", ...] - array of of supported MIME-types (RFC 2046). Empty means payload agnostic

See example

REST

• type: REST
• endpoint: { "url": "scheme://address:port"}
• url describes the endpoint URL (RFC 3986)
• additional fields can be defined
• methods: ["GET", "PUT", "POST", ...] - array of supported HTTP methods (RFC 2616)
• content-types: ["application/json", ...] - array of supported MIME-types (RFC 2046)

Example

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.

REST API

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.

As described above, the path is a configuration parameter setting the path in the catalog API endpoint URL.

CRUD

• /path returns all registered services as ServiceCatalog
• methods: GET
• /path/ endpoint for creating new entries in the catalog
• methods: POST
• /path/<service-id> returns a specific service registration given its unique id as a Service
• methods: POST (create), GET (retrieve), PUT (update), DELETE (delete)
• <id> id of the registration

Filtering

• /path/<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 Service 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>

Example

curl http://catalog.example.com/sc/services/meta.serviceType/prefix/_mqtt

will return all services in the catalog which meta.serviceType starts with _mqtt (as MQTT broker defined in the example above)

Pagination

The Services returned in services array in ServiceCatalog are paged using the page and per_page parameters.

The results are then include the following additional entries:

• page is the current page (if not specified - the first page is returned)
• per_page is the number of entries per page (if not specified - the maximum allowed is returned)
• total is the total number of Services in the catalog

Example

curl http://catalog.example.com/sc?page=1&per_page=10 curl http://catalog.example.com/sc/services/meta.serviceType/prefix/_mqtt?page=1&per_page=10

Versioning

API version is included as a parameter to the MIME type of request/response:

application/ld+json;version=0.1