Prism

Prism is a set of packages for API mocking with OpenAPI Specification v2 (formerly known as Swagger Specification) and OpenAPI Specification v3.

For example, given an API specification:

You can spin up a mock HTTP server and respond realistically based on your requests

The set of packages are made up of:

core: basic interfaces and abstraction for API descriptions
http: A Prism implementation to work with HTTP Requests
http-server: A Fastify instance that uses Prism to validate/mock/respond and forward to http requests
cli: A CLI to spin up servers locally easily

Look at the relative repositories' READMEs for the specific documentation.

Note: This branch refers to Prism 3.x, which is the current version most likely you will use. If you're looking for the 2.x version, point your browser to the 2.x branch

Installation

Most of the users will probably want to use the CLI, which is a Node module, and can either be installed via NPM or Yarn…

npm install -g @stoplight/prism-cli
# or
yarn global add @stoplight/prism-cli

…or if you do not want to install Node, you can either use the installation script (if you're using Linux or MacOS)…

curl -L https://raw.githack.com/stoplightio/prism/master/install | sh

…or download the latest release from GitHub directly. We offer binaries for Windows as well.

Usage

CLI

We'll present here only the main use cases. For a complete overview of the CLI, you can consult the relevant documentation ⇗.

Mock server

Running Prism on the CLI will create a HTTP mock server.

prism mock https://raw.githack.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml
✔  success   Prism is listening on http://127.0.0.1:4010
●  note      GET        http://127.0.0.1:4010/pets
●  note      POST       http://127.0.0.1:4010/pets
●  note      GET        http://127.0.0.1:4010/pets/{id}
●  note      DELETE     http://127.0.0.1:4010/pets/{id}

Then in another tab, you can hit the HTTP server with your favorite HTTP client.

curl -s -D "/dev/stderr" http://127.0.0.1:4010/pets/123 | json_pp
HTTP/1.1 200 OK
content-type: application/json
content-length: 85
Date: Thu, 09 May 2019 15:25:40 GMT
Connection: keep-alive

{
   "tag" : "proident et ",
   "id" : -66955049,
   "name" : "ut consectetur cillum sit exercitation"
}

Responses will be mocked using realistic data that conforms to the type in the description.

Determine Response Status

Prism can be forced to return different HTTP responses by specifying the status code in the query string:

curl -v http://127.0.0.1:4010/pets/123?__code=404

HTTP/1.1 404 Not Found
content-type: application/json
content-length: 52
Date: Thu, 09 May 2019 15:26:07 GMT
Connection: keep-alive

The body, headers, etc. for this response will be taken from the API description document.

Request Validation

Requests to operations which expect a request body will be validated, for example: a POST with JSON.

curl -X POST -s -D "/dev/stderr" -H "content-type: application/json" -d '{"tag":"Stowford"}' http://127.0.0.1:4010/pets | json_pp

This will generate an error, conforming the application/problem+json specification:

HTTP/1.1 422 Unprocessable Entity
content-type: application/problem+json
content-length: 274
Date: Thu, 09 May 2019 16:36:38 GMT
Connection: keep-alive

{
   "detail" : "Your request body is not valid: [{\"path\":[\"body\"],\"code\":\"required\",\"message\":\"should have required property 'name'\",\"severity\":0}]",
   "type" : "https://stoplight.io/prism/errors#UNPROCESSABLE_ENTITY",
   "title" : "Invalid request body payload",
   "status" : 422
}

This error shows the request is missing a required property name from the HTTP request body.

What's next for Prism?

Server Validation
Accept header validation
Content header validation
Security Validation
Dynamic Mocking (use JS to script custom interactions)
Forwarding proxy with validation
Recording traffic to spec file
Data Persistence (turn Prism into a sandbox server)
Support files ending with .yml and extension-less files

FAQs

Requests with base paths are failing. Why?

Base paths are completely ignored by the Prism HTTP server, so they can be removed from the request. If you have a base path of /api and your path is defined as hello, then a request to http://localhost:4010/hello would work, but http://localhost:4010/api/hello will fail.

How can I debug Prism?

Check out our debugging section ⇗ in the contribution docs ⇗.

Contributing

If you are interested in contributing to Prism itself, check out our contributing docs ⇗ and code of conduct ⇗ to get started.

adriengibrat / prism