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:
- Optic observes some API traffic (we call each of these batches a Capture)
- 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
- 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
locationshould be marked as
- A new field called
progresshas been added to the response
- A 404 Response was observed for
Get User by ID, add it!
- As you review the diffs, you are asked to Approve or Ignore these suggestions (similar to staging/unstaging code in Git).
- 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?
To start a capture, run
When you are finished, stop the process and follow the link Optic prints to review your API diff.