Configure your API to run with Optic

Optic documents your APIs as you build them by observing development traffic and learning your API's behavior. The CLI is constantly diffing your API’s behavior against its specification; ensuring every change to the API gets detected, documented and code reviewed by your team.

How does Optic monitor local traffic? Optic starts your API project locally. It provides the project a port, and then creates a local proxy to observe traffic to your application. You use your API through Optic, and Optic observes the requests and responses. These are presented to you in the Optic Dashboard to create an API specification.

When would I run my API with Optic? This is ideal when running a project locally, as it manages not only the Optic proxy but the application lifecycle. It allows for Optic to step in on the port your project usually starts on, making integration with existing tests and workflows seamless. If the project lifecycle is not easily managed with a single command, or the project is located on a remote system (such as behind an Amazon API Gateway), we'd recommend using an intercept environment as it is more feature-rich. Only use a proxy task for new projects if these other options are not feasible.

Configure your API to run with Optic#

Optic tasks are configured in the optic.yml file. This file is created in your API project's root directory when you run api init. Tasks each require a name, and take the following configurations:

  • command The command that starts your API locally. Optic provides an environment variable, PORT, on which the API project is expected to listen. If your project doesn't expect to start on PORT, you may need to pass that in the start command or by a small code change.
  • inboundUrl The URL at which Optic will listen for traffic and proxy it to your API project. We generally recommend setting this to localhost on the port your API uses today, as Optic will give your application a non-conflicting port to use at startup. This lets you use your existing tests and workflows without changes.

For example, if you ran api init and then wanted to set up a task to document your json-server project which accepts a port by command line, your optic.yml would look like this:

name: "todo-js"
command: node server.js --watch db.json --routes routes.json --port $PORT
inboundUrl: http://localhost:3001
Make sure your API starts on $PORT

Optic assumes your API can be started on a specific port, which Optic assigns. To do this, Optic provides $PORT as an environment variable. You'll either need to map this variable to a flag your API framework looks for, or modify your code to look for the $PORT variable when starting up.

on Windows, optic.yml commands are interpreted by the Command shell

By default, Node uses the built-in Command shell on Windows when asked to start a child process. This interprets commands differently from bash. Tools like cross-env help manage this for cross-platform projects. On Windows only projects, you can target Command shells directly. Here's a few Windows tips:

  • To expand an environment variable such as PORT, use %PORT% instead of $PORT
  • When invoking a program or script, use Command shell format (for example, ./application on Linux/MacOS would be application on Windows.)

Running an Capture Session#

To start an capture session, run api start. In the example above, this starts up the json-server project, passes it a port, and starts a proxy that forwards all traffic on to the application. Initially we ran this json-server project on port 3001, so we set inboundUrl to http://localhost:3001 and told the application to start on the PORT environment variable, which is passed to it by Optic in the command as a parameter. Existing tests, such as Postman tests, can be sent to port 3001 without any changes and Optic will observe those requests:

$ api start
[optic] Review the API Diff at http://localhost:34444/apis/1/diffs
[optic] Optic is observing requests made to http://localhost:3001
JSON Server is running
GET /todos 200 7.785 ms - -
GET /todos/0fe639b6 200 3.739 ms - 143
PATCH /todos/0fe639b6 200 21.253 ms - 143
POST /todos 201 4.818 ms - 150
GET /notyetimplemented 404 1.683 ms - 2

Optic provides a running list of URLs seen during a capture session. When you're finished, terminate the Optic session with ctrl+c. The session will end, bringing down both the proxy and the application run with the command parameter. Continue on to create your initial API specification with the data collected from api start

Next Steps

  1. Use Optic to write the initial API Specification
  2. Run your tests through Optic
  3. Share Optic with your Team