Public | Automated Build

Last pushed: 3 years ago
Short Description
A Straightforward REST Service Registry
Full Description


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


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.

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.


Gasconade provides basic service discovery using the Swagger specs 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

To give the proxy a quick test drive, insert the Swagger "petstore" example (test/ 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:

Attribute Data Type Description
x-serviceName string A machine-readable identifier for the name of the service the spec is for.
x-published boolean Set this to TRUE to allow clients to discover this spec.
x-responses ResponseMocks[] An array of mocked responses, used to configure MockServer (extension on Response Object).
x-requests RequestMocks[] 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.

Attribute Data Type Description
body BodyMatch The body to match
parameters array Array of parameters used for matching
response Reference 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).

Attribute Data Type Description
body Any The body of the response
stringify boolean If TRUE, the body is assumed to be JSON and will be passed through JSON.stringify() before sending to MockServer


Attribute Data Type Description
type string One of "STRING" or "REGEX" or "JSON" or "JSON_SCHEMA" or "XPATH" or "PARAMETERS"
value string/object If type equals "JSON" or "JSON_SCHEMA", value may be an object (will be stringified before sent to MockServer), string otherwise

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.

Docker Pull Command
Source Repository