# legion-discovery

A simple service discovery service based on Legion, that natively supports
the idea of interface versions, and the idea that clients may only be
interested in finding certain (compatible) versions of the services they
are looking for.

The initial motivation for this project is to act as a test driver for the
[Legion](https://github.com/owensmurray/legion#readme) framework. Since the
status of that framework is still experimental, the status of this service is
also experimental.

- [API](#api)
    - [`POST /v1/ping/:serviceId/:version`](#post-v1pingserviceidversion)
    - [`GET /v1/services/:serviceId`](#get-v1servicesserviceid)
    - [`GET /v1/services/:serviceId/:versionRange`](#get-v1servicesserviceidversionrange)
    - [`GET /v1/graph`](#get-v1graph)
- [Content Types](#content-types)
    - [`application/vnd.legion-discovery.instance-list+json`](#applicationvndlegion-discoveryinstance-listjson)
    - [`application/vnd.legion-discovery.ping-request+json`](#applicationvndlegion-discoveryping-requestjson)

## API

### `POST /v1/ping/:serviceId/:version`

Register a service. Registration expires in 30 seconds.

- Request
    - Content-Type: [`application/vnd.legion-discovery.ping-request+json`](#applicationvndlegion-discoveryping-requestjson)
- Response `204 No Content`: indicates a successful registration.

### `GET /v1/services/:serviceId`

Returns all current instances of a service, regardless of version.

- Response `200 Ok`
    - Content-Type: [`application/vnd.legion-discovery.instance-list+json`](#applicationvndlegion-discoveryinstance-listjson)


### `GET /v1/services/:serviceId/:versionRange`

Returns the service instances that match the requested version range. The
version range syntax is the same as what cabal understands
(e.g. `>= 0.1 && < 0.2`). You are really going to want to make sure and url
encode this segment of the url.

- Response `200 Ok`
    - Content-Type: [`application/vnd.legion-discovery.instance-list+json`](#applicationvndlegion-discoveryinstance-listjson)

### `GET /v1/graph`

Returns a visualization of the service interactions. This endpoint supports
multiple content types via the `Accept` header.

- Response `200 Ok`
    - Content-Type [`image/svg+xml`](https://www.w3.org/TR/SVG11/)
    - Content-Type [`text/vnd.graphviz`](http://www.graphviz.org/content/dot-language)


## Content Types

### `application/vnd.legion-discovery.instance-list+json`

    {
        "https://host1:8080": {
            "version": "1.0.2.0"
        },
        "https://host2:8080": {
            "version": "1.0.2.0"
        },
        "https://host3:8080": {
            "version": "1.0.2.0"
        }
    }

### `application/vnd.legion-discovery.ping-request+json`

    {
        "serviceAddress": "https://host3:8080"
    }