Changing Shapes

Optic is great for generating API documentation. It will also monitor your API traffic and look for changes to endpoints that have already been documented. These changes may be intentional, such as adding, removing, or changing capabilities of an existing endpoint. They may also be unintended, which may have undesirable consequences. Optic will flag these for review and allow you to catch issues before they reach production.

Let’s walk through an example of an intentional change, where we add a body value to the response from the posts endpoint.

Make the change in your container

Before we can see the results of a change, we need to make one. A script living on the demo container will handle the necessary changes.

  • Find your container ID. You should have one demo container running. Grab its ID with docker ps | grep useoptic/optic-demo.
  • Run a script to make the necessary changes. docker exec <container ID> "/root/"

These commands will add the body field to the posts endpoint, and get everything ready for us to see the changes.

Revisit the posts GET endpoint

Navigate to http://localhost:4000/posts again. If you’ve been following along in the demo, there are now three posts in the response. Also, you’ll see that each post has a body entry.

Optic observed this request, and noticed that it does not look like previous requests. Navigate to http://localhost:34444/apis/1/diffs to see that we have a new interaction to investigate with 3 diffs.



Click through the /posts endpoint to bring up a diff review. We don’t need to click through modal dialogs to document the endpoint itself or its description, as we’ve already seen GET requests to this endpoint. Optic recognizes this is a change to previously observed behavior, and lets us review the changes directly. Note it points out that body is an undocumented field.



Optic needs our input to decide the appropriate resolution. The Optic icon on the review action dialog pulses to indicate there’s an action to take. Since this is an intended change, we’ll want to make sure we select the radio button to Add body. Then, click Approve.

As before, Optic gives us a chance to review the commit message, which is automatically generated to indicate the body field was added to the specification. Click Commit changes to finish this diff review. That’s it! The shape of the data has been updated in the documentation. Click through the documentation button at the bottom of the left navigation bar and check out the updated GET endpoint for /posts.


Next steps

With Optic, we can document our endpoints and capture changes in their behavior. In our next example, we’ll observe and document some traffic from a parameterized path to see how we can build out additional context. Or, if you’re ready to try Optic on your own API project, check out our installation instructions to get set up in your local environment.