Skip to main content

Documenting existing API Endpoints

Documenting the endpoints in your API takes seconds with Optic. Just click "+" and name the endpoint.

Outcome: Add the first endpoints to your Optic specification

Do this ⤵️

If we run api status --review, the Optic UI will open, and we should see some undocumented URLs:

8 Unmatched URLs observed in a traffic capture

Documenting your first endpoint#

On the left you'll see all the URLs Optic observed that do not match any of the endpoints in our specification. If any endpoints are along a documented path, Optic will let us know. On the right side of the page are all the endpoints that have been learned. Endpoints with a green background have just been learned, and we'll need to save them to our specification. Endpoints without a background are already saved in our specification.

Learning from traffic

Do this ⤵️

  • To keep it simple, choose an endpoint without any path parameters ie GET /todos (we'll learn how to document endpoints with path parameters next).
  • Click the "+" icon in the row:

Optic used everything it learned watching traffic to document this endpoint for us. You could look at the same information and manually write the spec file yourself, but Optic has made it much easier by doing that work for you.

Optic shows what it knows about the endpoint

Do this ⤵️

  • Name the endpoint: Here, the Gets all todos description was added.
  • Click through Add Endpoint to add it to the specification

The first endpoint is staged

Optic has staged the GET /api/todos endpoint for commit. That is, Optic has learned about this endpoint from the traffic it observed, and is ready to save what it learned to the spec. Learning an endpoint is like staging changes in Git. It is not until you click Save Changes that you commit those changes to the spec.

You can safely stage as many endpoints as you like before committing them to your documentation.

Do this ⤵️

  • For now, let's save this endpoint and give it a commit message:

The first endpoint is committed

What happens when Optic sees a different shape?#

Optic learns your API's behavior incrementally. If you missed an endpoint in this capture or if the example Optic learned originally did not include every possible response code, field or other variations, that's ok. Optic will suggest those additions to your API specifications as it observes more traffic.

When you make changes to your API, Optic can help you document those too. You can learn more about how Optic helps you change your API here.

What about Path Parameters?#

Most API endpoints are parameterized, ie GET /todos/:todoId/status. Optic makes it easy to document parameterized endpoints as well, let's try that next!