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

Collection

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

Registration

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 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

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.

CRUD

• /sc returns all registered services as Collection
• methods: GET
• /sc/:id returns a specific service registration given its id as a Registration
• methods: POST (create), GET (retrieve), PUT (update), DELETE (delete)
• :id id of the registration

Filtering

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

Example

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)

Versioning

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

application/ld+json;version=0.1