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

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)

The rest of the fields have the following meaning:

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

Collection

The entry point of the Service Catalog 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

Example

For 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://gando.fit.fraunhofer.de: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"
	}

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.

The API root (Collection) is by default at /sc

CRUD

TODO

Filtering

TODO