legion-discovery-0.3.0.0: README.md

# 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`](#post-v1ping)
    - [`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`

Register a service. The service name and version are obtained via the
`User-Agent` header field. Registration expires in 30 seconds.

- Request
    - Content-Type: [`application/vnd.legion-discovery.ping-request+json`](#applicationvndlegion-discoveryping-requestjson)
    - Headers:
        - `User-Agent`: The `User-Agent` request header is
          mandatory, and must conform to the grammar specified in
          [RFC-2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43)
          and, further, must provide the product version that RFC-2616
          describes as optional.
- Response `204 No Content`: indicates a successful registration.

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

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

- Request
    - Headers:
        - `User-Agent`: The `User-Agent` request header is
          mandatory, and must conform to the grammar specified in
          [RFC-2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43)

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

- Request
    - Headers:
        - `User-Agent`: The `User-Agent` request header is
          mandatory, and must conform to the grammar specified in
          [RFC-2616](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.43)

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