Documenting your API

By observing actual API traffic, Optic can quickly learn the contract of any API – even those with no documentation today.

Here’s how it works:

  1. Optic observes some API traffic (we call each of these batches a Capture)
  2. Optic diffs each request/response in the batch against the contract
    • When there is no diff, Optic continues to the next item in the batch
  3. When a diff is produced, Optic presents its suggestions for updates you should make to your contract. For example:
    • A new endpoint was observed, add it!
    • The field location should be marked as optional
    • A new field called progress has been added to the response
    • A 404 Response was observed for Get User by ID, add it!
  4. As you review the diffs, you are asked to Approve or Ignore these suggestions (similar to staging/unstaging code in Git).
  5. Commit the changes! Now your contract is up-to-date

Next time you start a capture your traffic will be updated against the updated contract.

Can I document my API incrementally? Yes! Documenting your API with Optic is not a one-shot process. The tool is designed to be used continually throughout the lifetime of your API. The approach of diffing the API traffic naturally allows for:

  • Learning an API contract incrementally
  • Updating the contract as your API evolves
  • Detecting unplanned/accidental changes in your API’s behavior

How should I create traffic? Just run api start to begin capturing a dataset for Optic to learn from. You might consider using the following approaches to create traffic:

  • Your API tests
  • A Postman collection
  • A Web or Mobile UI that consumes the API
  • Curl, HTTPie or similar tool

How much data do I need? Like all machine learning problems, the more representative data you provide Optic, the better the resulting API contract.

What does ‘more data’ mean?:

  • Coverage - is there traffic for all your endpoints?
  • Errors + Happy Path - have you only sent valid requests or both valid and invalid ones?
  • Polymorphism - are there examples of optional field provided and excluded, of polymorphism expressed?

Starting a Capture

To start a capture, run

api start

When you are finished, stop the process and follow the link Optic prints to review your API diff.

Table of contents