Capturing Traffic

Capturing Traffic

Optic Capture helps create OpenAPI specifications and keep them up to date by examining the traffic to your API. Under the hood the following happens when running Capture,

  • Your API is started via a command you provide.
  • A reverse proxy is configured to send traffic to your API.
  • A command or set of requests you provide is run, generating traffic to the proxy.
  • Optic observes the traffic as it passes through the proxy.
  • These observations can then be used to create or update your OpenAPI specification.

By default, all of this happens locally. Your capture details and API specification are not sent to Optic unless you explicitly opt into uploading your results to Optic Cloud.

You can view the capture CLI options with,

optic capture --help


Capture is configured inside your optic.yml file. Whether or not you already have an optic.yml, getting started is easy via the optic capture init command.

You can insert a configuration block into your optic.yml (generating one if necessary) with a complete, commented configuration example:

optic capture init [./path/to/your/]openapi.yml

Configuration Reference

optic capture init can also display a capture configuration example to stdout, making it a useful reference and source of truth for the Capture configuration options. For example, the following command will display the configuration block without making any changes to optic.yml.

optic capture init --stdout openapi.yml
      # The command to run your server.
      # Optional: If omitted, Optic assumes the server is running or started elsewhere.
      command: your-server-command
      # The url where your server can be reached once running.
      # Required: Can be overridden with '--server-override'.
      url: http://localhost:8080
      # A readiness endpoint for Optic to validate before sending requests.
      # Optional: If omitted, perform no readiness checking.
      ready_endpoint: /
      # The interval to check 'ready_endpoint', in ms.
      # Optional: default: 1000
      ready_interval: 1000
      # The length of time in ms to wait for a successful ready check to occur.
      # Optional: default: 10_000, 10 seconds
      ready_timeout: 10_000
    # At least one of '' or 'requests.send' is required below.
      # Run a command to generate traffic. Requests should be sent to the Optic proxy, the address of which is injected
      # into 'run.command's env as OPTIC_PROXY or the value of 'run.proxy_variable', if set.
        # The command that will generate traffic to the Optic proxy. Globbing with '*' is supported.
        # Required if specifying ''.
        command: your-test-command
        # The name of the environment variable injected into the env of the command that contains the address of the Optic proxy.
        # Optional: default: OPTIC_PROXY
        proxy_variable: OPTIC_PROXY
      # Have Optic generate traffic to the proxy itself by specifying endpoint details. A request's 'data' attribute
      # is converted to JSON and sent along with the request.
        # path: Required
        # method: Optional: default: GET
        # data: Optional: If omitted on a POST request, default: {}
        # headers: Optional: If 'content-type' is omitted, it is set to 'application/json;charset=UTF-8'.
        - path: /
          method: GET
        - path: /users/create
          method: POST
            content-type: application/json;charset=UTF-8
            name: Hank
      # The number of parallel requests to make when using 'requests.send'.
      # Optional: default: 4
      request_concurrency: 4

Once you've set up your capture configuration you're ready to update, create, and verify your OpenAPI spec!

Create/Update an OpenAPI spec

You can persist changes to (or create) your OpenAPI spec by including --update <mode> in your capture command.

 optic capture openapi.yml --update automatic
Initializing OpenAPI file at openapi.yml
 Successfully captured requests
Learning path patterns for unmatched requests...
Documenting new operations:
 GET /
 GET /users
 POST /users/create

There are 3 update modes,

interactiveInteractively prompt and confirm observed changes to new and existing endpoints.
automaticAutomatically apply observed changes to new and existing endpoints.
documentedAutomatically apply observed changes to existing endpoints only.

Verify an OpenAPI spec

If you already have an OpenAPI spec and run capture without the --update <mode> option, the requests observed will be compared against your spec without making changes to it.

$ optic capture openapi.yml
 Successfully captured requests
 GET /
  200 response
  [404 response body] body is not documented
 GET /users
   200 response
 POST /users/create
   Request Body,  201 response

Next Steps

View examples generating traffic to Optic, or import existing requests from HAR files or Postman collections.