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.
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:
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
- When invoking a program or script, use Command shell format (for example,
./applicationon Linux/MacOS would be
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
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:
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