kleijnweb/gasconade repository overview

⁠Gasconade

STATUS: Exploratory (Not all features listed here are implemented, let alone stable)

⁠A Straightforward REST Service Registry

Gasconade allows you manage your service APIs using Swagger⁠ specs, serving as a central hub for all your API documentation.

Gasconade enables you to:

• Use Swagger specs for Service Discovery
• Allow developers to explore available services and API docs
• Specify request/response mocks (and proxy them using MockServer⁠ as a backend)
• Bypass firewalls by poxing API calls

⁠Installation

⁠Using Docker Compose

Using Docker Compose⁠ you can deploy Gasconade, MongoDB and MockServer with a single command:

$ docker-compose up

⁠Manually

Gasconade runs on NodeJS⁠ (0.11+) and requires a running instance of MongoDB⁠ to work. To be able to mock services you'll need to install and run MockServer. There are a lot of options⁠, but the easiest non-Docker way is using the npm module:

$ npm install mockserver-grunt

Gasconade will pick up on the module being installed and start and stop MockServer automatically. No Grunt⁠ required.

⁠Usage

Gasconades simple GUI should be pretty self-explanatory. Chances are you want to do most of your managment tasks using the REST API. The documentation is rendered using Gasconades own Swagger spec and can be found here⁠.

⁠Spec Versioning

Gasconade leaves most the versioning concerns to the Swagger spec. It does however impose one constraint:

You cannot add a spec that already exists for a service at the same version, unless it is known to be a development version of the spec. Eg you cannot add a spec for version 1.0.1 for service "foo", if that version was already registered. This avoids abiguity, and/or unstable specs that clients may already depend on. To indicate you are registering a development version, prefix the version with the string "dev-". Any previous version with the same serviceName and version will be overwritten.

⁠Discovery

Gasconade provides basic service discovery using the Swagger specs info.host and info.basePath attributes. Clients can query Gasconade using a serviceName and version, which will return the full spec, including before-mentioned attributes.

Because of this, it is not possible to add more than one spec with the same hostname and basePath, even if the versions differ. Either the hostname or basePath should reflect the version of the API.

Clients can query Gasconade for specs by using the URI scheme /specs/{serviceName}/{apiVersion}.

⁠Proxying Service Calls

Gasconade allows you to proxy service calls, simplifying firewall setup and in general providing greater control over network traffic. Using Gasconade to proxy calls means zero extra setup and maintenance, as opposed to using HAProxy or Nginx. While Gasconade should perform more than adequate for most use cases, don't expect it to be as fast and reliable as either of those alternatives. Currently, Gasconade proxies to port 80 only.

Clients can use Gasconade as a proxy for any service by using the URI scheme /proxy/{serviceName}/{apiVersion}/*. The wildcard in this scheme represents anything after info.basePath (paths + any URI parameters from the spec). The proxy supports the following HTTP methods:

• GET
• PUT
• POST
• DELETE
• PATCH

To give the proxy a quick test drive, insert the Swagger "petstore" example (test/fixtures.sh) and query for a pet through the proxy:

curl -X GET --header "Accept: application/json" "http://localhost:3000/proxy/pets/1.0.0/pet/1440865504648"

NOTE: This perticular "Pet ID" was valid at the time of writing, you may need to try a different one to get a non-error response from the Swagger demo app.

⁠YAML

Gasconade currently does not support YAML; it is on the TODO list.

⁠Swagger Vendor Extensions

The model in the docs for specs is simply the Swagger spec⁠. Gasconade utilizes the following extensions to that spec:

⁠Mocks

Gasconade allows you to extend your Swagger specs with request and response "mocks".

⁠RequestMock

This is used to configure the "httpRequest" part of a MockServer expectation. Being an extension of Path Item Object⁠, much of the config needed must be omitted.

⁠ResponseMock

This is used to configure the "httpResponse" part of a MockServer expectation. Being an extension of Response Object⁠, much of the config needed must be omitted. You only need to specify the response body, and make sure the object can be referenced (see Swagger docs⁠ on references).

⁠BodyMatch

⁠Future Enhancements (2.0)

• Support POST-ing and uploading specs in YAML
• Validation of proxied calls (enabling ad hoc services)
• Improve SwaggerUI⁠-like doc rendering (currently using the client side JS from SwaggerUI)
• Move to hapi and create Angular UI as a separate project
• Intergate with Consul⁠ for service discovery
• Share references (eg. Model specs) between specs)

⁠License

Gasconade is made available under the terms of the LGPL, version 3.0⁠.