Parameterized Routes

Optic will automatically generate documentation based on your input from observed traffic. It also allows you to provide additional context where needed, such as adding descriptions to endpoints. One other place where additional context may be added is when documenting parameterized routes.

Retrieve a few posts individually

We now have three posts in our database, with bodies. Until now, we’ve retrieved them with a GET request to the /posts endpoint. This has worked well, though as we add more data to our system we’ll eventually want to be able to specify a single post to view. Our API has an endpoint available, /posts/{id}, which will let you specify a post ID and retrieve just that object. Let’s try that now:

Let’s review these interactions in the Optic dashboard. We should see two undocumented URLs to review. Each ID looks like a separate path: /posts/1 and /posts/2 look like different endpoints until we add further context.


Click on /posts/1 to start documenting the /posts/{id} route. Optic will bring up the usual undocumented modal dialog. This time, instead of clicking through, click the 1 in the path under “click any path component to make it a parameter”. Optic will wrap the value as a parameter, and ask for additional context to define the example the value provides. In this case, let’s say it’s an example of an id.


As we’ve identified this part of the path is a parameter, Optic also identifies any other undocumented URLs that match this endpoint. In our case, it identified /posts/2 as being another observed example of /posts/{id}. Click Next to add a description, such as Retrieves a post by id. Click Done to review the shape of the request and response. It will show no request body as expected, and two response bodies. Click through to the second response body to see that the path with id 2 has been captured as an example of the parameterized path.


Click Document (2) bodies and approve the commit by clicking Commit changes. This should resolve all undocumented endpoints. Click through the Documentation icon on the bottom of the left navigation bar to see the results. Click through the new parameterized route to see how the shape of the response was documented.


Next steps

We’ve seen how to document our APIs, handle changes, and add additional context where necessary. Sometimes, we may need to not document interactions such as service requests or other noisy paths. Instead of polluting the documentation, we’ll walk through Ignoring an endpoint in our next example. 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.