Optic allows you to view the shape of the data moving through your API in both directions. It runs as a proxy to capture and summarize this data in the Optic dashboard. From the dashboard, you can observe which routes are called and how. The Optic dashboard allows you to build quick, powerful documentation and observe any changes in behavior or use over time.
Please grab the demo container and follow along as we walk through documenting your first route.
You can follow along and explore the Optic workflow for documenting an API yourself in Docker. If you’d rather just read along, jump ahead to Make the first GET request
Go ahead and pull our Optic demo image from the Docker repository:
docker pull useoptic/optic-demo:latest
Then, run the image. You’ll want to map ports 4000 (the Optic API Proxy) and 34444 (the Optic dashboard) to the container. If they’re not already in use in your environment, you can run the following command:
docker run -p 4000:4000 -p 34444:34444 useoptic/optic-demo
You should be ready to go!
Navigate to the Optic dashboard at http://localhost:3444/apis/1/diffs to get started. Since we haven’t yet observed any traffic, you’ll see an empty page confirming that Optic is up and ready to go. Note the URL path has a GUID. This keeps track of the monitoring session, to help observe changes. You can always see the latest ongoing capture by omitting the GUID.
This demo uses typicode’s json-server project (see Special Thanks) which comes with several routes by default. We’ll start with the
posts route. In a new tab, navigate to http://localhost:4000/posts to trigger a GET request.
Port 4000 is the default Optic API proxy port for this demo. All requests should be sent here. Optic will forward these requests to the project under observation (json-server), and relay back the response transparently. Here our example system has responded with a JSON array of one post, which Firefox has helpfully expanded.
Return to the Optic dashboard. Optic observed the request as an interaction. Since this is our first observation, it’s still an undocumented endpoint. The Optic dashboard will show the undocumented URL and request type (GET):
Click on the undocumented URL to start documenting the API. You’ll step through two modal dialogs.
The first dialog box lets you specify a pattern for the URL based on the path, converting any path elements to parameters as necessary. We haven’t observed any parameters yet, so click through Next this time.
Next, you’ll get to document what this endpoint does. In this case, we know it
Lists all posts and their contents so feel free to copy that over and click Finish.
The Optic dashboard will present a summary of the new route, showing the observed Requests and observed Responses. By default these are both checked, which will document both the request and response bodies. In this case, we’ll leave both checked.
Scrolling down, the Optic dashboard presents an example of the endpoint in action. Optic assembles this example based on its observations alone: all we had to do was call the endpoint properly and provide a short description for context. Optic generates the rest.
On the left, we see an example interaction from the observed traffic. This is used to generate the documented shape of the data, on the right. The data shape is Optic’s interpretation of the keys and value types expected based on observed traffic. Here, we see both author and title are observed to be strings. This shape information will be used in the generated API documentation.
Scroll back up and click Document (2) bodies to proceed. Optic will commit the generated documentation to its database. First, we are given an opportunity to edit the commit message, which by default describes the requests and responses documented. For now, click Commit changes to accept the default commit message and return to the Optic dashboard.
The Optic dashboard will now look similar to when we started, with no routes shown. The counts have changed: we now have 1 interaction observed with no undocumented endpoints. Great job! To review the documentation, click on the document icon at the bottom of the left navigation bar.
Optic keeps all of the generated documentation ready to go. The documentation view by default shows the routes and their methods, with the brief descriptions given to each.
Click the Full documentation section to expand the responses from the endpoint. Here we can see a 200 HTTP status code should be accompanied by a list of objects in JSON. Additional notes can be added to any field with a + by clicking on it.
Congratulations, you’ve documented and reviewed your first endpoint!
Next, we’ll walk through a POST request and see how we document different methods on a single route. 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.
- All of Optic’s contributors. Thanks for making Optic great! (under MIT License)
- typicode’s json-server project (under MIT License) which allows you to mock up an example API very quickly, with some default routes ready to go.
- Docker, for providing the tooling used here to package up and deliver a demo environment. (license reports)
- Postman and curl, used in the [POST] demo (licenses vary)