Documenting External (Public) & Internal (Private) APIs

Hello, I’m looking for some best practice guidance to creating API documentation. We have some API routes that we’d like to make available for public access, as well as having some API routes documented for private/internal use by the development team. Technically the private routes are accessible, but we aren’t ready to support or encourage use publicly while we tighten up the schema.

There doesn’t appear to be a way to flag certain routes in a single collection as private/public, so my thought is to create a ‘public’ collection and fork it to an internal, non-published collection. When a route is made public, we can merge it into the internal/private collection.

I think this is okay, but there may be some confusion/conflicts when developers are updating internal documentation and it needs to be manually updated on the external/public side.

Is this the best practice or is there an alternative approach I should consider? Would love to hear how others are approaching this problem.

I’m having the same situation here, have you been able to solve this?

You are doing it exactly the same way we do it at my company, @Tim

We have dedicated public collections for the external APIs and have non-published collections for the APIs that are currently in progress or that haven’t been released yet.

:clinking_glasses: