By observing your API traffic, Optic learns the API contract, detects whenever the API’s behavior changes, and helps you test the API.
The goal of this tutorial is help you configure the Optic CLI to start your API and monitor the traffic from your development environment.
# your original start command node start-server.js # is substituted for Optic's start command api start
First, open a terminal and navigate to an API project. Then run:
api init Optic will add an
- Describes how the
api starttask should start your API
- Configures some Advanced Options for Captures (more on this later)
optic.yml file and the
.optic folder should both be checked into version control.
Now it’s time to show Optic how to start your API. Once completed you’ll be able to run your API using Optic’s
api start command.
optic.yml file in your favorite text editor and change the
name: Demo API tasks: start: command: echo "Setup A Valid Command to Start your API!" baseUrl: http://localhost:4000
command - the command used to start your API server. ie
npm run start-server It MUST:
- Start a long-running process (your API) that stays running until exited
- Be runnable from the same directory as the
optic.ymlfile w/o any special permissions
baseUrl - the URL where you want the API to be accessible locally ie
http://localhost:4000. It MUST:
- Be on a port/hostname that doesn’t require special permissions to bind to It SHOULD:
- Be the same URL you use for local development today, that way the API consumers don’t need to be updated.
Now you need to update your
command or code so that your API starts on the port Optic assigns it via the
OPTIC_API_PORT environment variable.
This usually requires one of the following:
- Updating 1-3 lines of code in your project
- A flag to be passed into your start
commandthat sets the API port to
Look below for examples of how to make this change in your API framework:
If you use
./gradlew bootRun to run your spring app, you just have to update your start command in your
start: command: ./gradlew bootRun
start: command: export SERVER_PORT=$OPTIC_API_PORT ; ./gradlew bootRun
Note: If you use maven to run your app, the same approach will work. Just make sure your optic.yml includes
export SERVER_PORT=$OPTIC_API_PORT ; so that the port that maven uses is the
Now when Optic runs your start command, your API will start on the port Optic assigns it.
Now it’s time to test that you have set up Optic correctly. The Optic CLI has a
check command for testing the integration one step at a time to help diagnose any problems.
Here’s an example of running
api check start with a working integration:
Now run the command in your project:
api check start
If Optic detects any issues with your API, it will provide a link to a fix in our documentation.
Need more help? Click here to start a chat.
Now that Optic is integrated, it’s time to document your API.