Link

Python

Table of contents

  1. Overview
  2. Run api init
  3. Configure api start task
  4. Give Optic the ability to start your API on a port it controls
    1. Flask Supported Requires Code Change
    2. Django Supported Requires Code Change
    3. FastAPI Supported No Code Changes
  5. Run api check to verify integration

Overview

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

Run api init

First, open a terminal and navigate to an API project. Then run:

api init

alt text

After running api init Optic will add an optic.yml which:

Note The optic.yml file and the .optic folder should both be checked into version control.

Configure api start task

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.

Open the optic.yml file in your favorite text editor and change the command and baseUrl fields:

optic.yml
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.yml file 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.

Give Optic the ability to start your API on a port it controls

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 command that sets the API port to OPTIC_API_PORT

Look below for examples of how to make this change in your API framework:


Flask Supported Requires Code Change

All Flask APIs contain a call to app.run(...). Just update this line to pass in Optic’s environment variable first:

Before

app.run(port=5000)

After

app.run(port=os.environ['OPTIC_API_PORT'] if 'OPTIC_API_PORT' in os.environ else 5000)

Note: If you are using flask run, simply adjust flask run to pass in the port

Before

flask run

After

flask run --port=$OPTIC_API_PORT

Now when Optic runs your start command, your API will start on the port Optic assigns it.

Django Supported Requires Code Change

Django runs by its manage.py file. To allow for optic, simply adjust it to use the Optic API Port

Before

... # other code
def main():
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')
    try:
        from django.core.management import execute_from_command_line
... # other code

After

... # other code
def main():
    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mysite.settings')
    try:
        from django.core.management import execute_from_command_line
        # Add Optic CLI as a port option
        from django.core.management.commands.runserver import Command as runserver
        runserver.default_port = os.environ['OPTIC_API_PORT'] if 'OPTIC_API_PORT' in os.environ else 8080
... # other code

Now when Optic runs your start command, your API will start on the port Optic assigns it.

FastAPI Supported No Code Changes

If you use the uvicorn command to start your FastAPI app, you just have to update your start command in your optic.yml file:

Before

start:
  command: uvicorn main:app # assuming your app is called main.py

After

start:
  command: uvicorn main:app --port $OPTIC_API_PORT # assuming your app is called main.py

Now when Optic runs your start command, your API will start on the port Optic assigns it.


Run api check to verify integration

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:

alt text

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.


All Done! Nice Work

Now that Optic is integrated, it’s time to document your API.

Start Documenting