When it comes to APIs, we need to version behavior, not just code. While Git versions your code, Optic versions the behavior of your APIs.
- API specs need history: The reason Git can power the change management workflows we use daily is because it keeps a history of every change, not the current state of any individual file. Similarly, Optic specs are a ledger of every API change ever made.
- API specs need evidence: Does the API actually work the way the spec says it does? You can't really know unless you compare it to real traffic and record evidence.
- Every API change should be documented, reviewed and approved: Whether you work code-first, design-first or both -- it's important to review the API with your team every time it changes.
Do I need to create traffic that covers the entire API each time I use Optic?
No. Previous Traffic -> Spec generators have been "one-shot". Optic instead learns your API incrementally. You can add endpoints one at a time, come back days later and add more. When you use Optic to validate your API behavior, it will give you a report about any API
Diffs it observed, and the API
Coverage from those tests.
- What happens when the API changes?
When the API changes, Optic detects a difference in the requests and/or reponses. Optic will report unexpected behavior, which you can see with
api status or on the diff page in the Optic dashboard. The diffs are reviewed in the dashboard, and can be documnted or ignored if they shouldn't modify the specification.
- What is this
specification.jsonfile? Do I check it in?
specification.json file is an event stream of every change to your API. The
specification.json is how Optic builds the current and historical state of your API specification. It must be checkd in with your project so your specification is stored alongside your API.
- I documented an endpoint incorrectly, can I delete it?
Yes! Endpoints may be deleted from either the documentation page or from the detailed documentation for a specific endpoint. When viewing the current documentation, click the edit button to start editing the specification, and the delete button to stage an endpoint for removal. Clicking save will make the change permanent. Deletes cannot be undone. Please review our detailed endpoint delete documentation.
- Optic documented something about my API incorrectly. Can I change it?
Currently, Optic will give you the opportunity to change how an endpoint is documented when it detects traffic that doesn't conform to the current specification. We're working on releasing more tools to help modify your specification proactively, through the Optic dashboard.
Optic Spec(ification)- A record of every change to your API since you initialized Optic in you project. Sort of like Git-history but for the API behavior. For Open Source users these events are recorded in
Optic Engine- the core of the Optic project that is responsible for ingesting traffic, computing diffs, and querying / mutating your Optic Spec. It is open source and written in Rust.
HTTPInteraction- Request/Response pairs that the Optic Engine reads when documenting your API or verifying its behavior
Capture- A set of
HTTPInteractions. Grouped by test run, build-id, or other qualifier to keep relevant traffic together.
Diff- When a
Captureis diffed against an
Optic Spec, the
Optic Enginewill return 2 sets:
Undocumnted URLs- similar to Git's "untracked files". These are URLs that do not match any endpoint that's part of your specification. If some of these should be included in your Spec, Optic makes it easy to document them in a few seconds.
Endpoint Diffs- similar to Git's "changes to be committed", these are new behaviors that do not match the existing ones documented for the given endpoint. Ie a new field named
addresswas seen in the 200 Response Body
API Coverage- Think Code Coverage, but for measuring the usage of different API endpoints, and their status codes. Coverage measures the % of your API's known surface area that a specific
Captureexercises. It's helpful when evaluating the quality / power of your tests. If you see 100% coverage in CI, and no diffs, that's a storing signal that your entire API is working as expected.
optic.yml- Optic's config file. Here you can set up various methods of capturing API Traffic, that can be shared with your team, and called upon in CI/CD.
task- aliases for the commands you use when building your API ie (
npm test). When run, with
api run taskName, the command executes, and any traffic handled by your API is captured.
environments- deployed versions of your API that you can intercept traffic to from the client side. ie
api intercept production --chromewill open your production webapp and collect all the traffic to your API that is seen in the Chrome Network tab.
Optic UI- Optic's equivalent of a Git client. Add new endpoints, and approve changes to existing ones. The code for this UI is Open Source
Endpoint- An API path ie
/todos/:todoIdpaired with an HTTP Method ie
Contribution- manually added titles, tags and descriptions added to the
Optic Specby users. Optic makes sure your contributions are retained over time as the spec changes.
Commit- When you use the
Optic UIto change your API spec, these changes are saved in relation to a specific point in time, the
API Changelog- a semantic comparison between two points in the Optic Spec history.
Spectacle- the GraphQL API Optic exposes for interacting with your
Optic Spec. It makes your
Optic Specend user programmable. This is what
Optic UI, and a lot of the more advanced functionality in the tool is powered by
Optic GitBot- Optic's GitBot, which adds
API Changelogsto your Pull Requests.
API Changelogs in Pull Requests- Just like GitHub shows you "Files Changed" between the base / head branch, the Optic GitBot will show you the API changes between the base / head branch.
API Checks- Enforce governance rules and your API design guides in CI. Write checks using
Spectaclethat prevent breaking changes to published endpoints, enforce naming conventions, etc. It's fully programmable.