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
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
Using Docker Compose
Using Docker Compose you can deploy Gasconade, MongoDB and MockServer with a single command:
$ docker-compose up
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.
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.
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.
Gasconade provides basic service discovery using the Swagger specs
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
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
The wildcard in this scheme represents anything after
paths + any URI parameters from the spec).
The proxy supports the following HTTP methods:
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.
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:
||A machine-readable identifier for the name of the service the spec is for.|
||Set this to TRUE to allow clients to discover this spec.|
||An array of mocked responses, used to configure MockServer (extension on Response Object).|
||An array of mocked requests, used to configure MockServer (extension on Path Item Object).|
Gasconade allows you to extend your Swagger specs with request and response "mocks".
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.
||The body to match|
||Array of parameters used for matching|
||A valid reference to a ResponseMock object in the spec|
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).
|body||Any||The body of the response|
||If TRUE, the body is assumed to be JSON and will be passed through JSON.stringify() before sending to MockServer|
||One of "STRING" or "REGEX" or "JSON" or "JSON_SCHEMA" or "XPATH" or "PARAMETERS"|
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)
Gasconade is made available under the terms of the LGPL, version 3.0.