How do I effectively build a Product on my on my public API?

I want to develop a new product on top of an existing public API. This will require functionality to be added to that API.

How do I develop and API for both public use (by other organisations) and internal use (by my product)?

I’m asking this because I think there may be conflict of approaches here.


Why is there a conflict? Why do I think that there is a difference between developing internal and public APIs?:

I think building a public API is hard. You have to think carefully about what you add and take things like versioning, and supporting old versions, seriously. I think public APIs are one of the most important place to get your code quality, documentation and domain modelling correct. I also think that it’s okay to develop internal APIs a little bit more recklessly, work at a quicker pace, ship experiments and make breaking changes.

Obviously it’s a spectrum. An internal api at google is probably a bigger deal than most companies’ public apis. But this seems like a reasonable statement: The more projects, people and organisations that depend on a contract in code, the more mutable that contract becomes.


Maybe I’m wrong. But if I’m not, how can I make sure that this mixed use case doesn’t result in a rushed public API, or a slow and inflexible approach being taking towards meeting the internal needs?

…TLDR stop here. Question over…

But let me share some things I’ve thought about:

1) Make all developments on the public API, do them with a high level of care and thought.

  • GOOD: One codebase. High quality changes.
  • BAD: – Slow – If it fails (for example under a lot of feature pressure from the business), the first I know of it is my public API being messed up. Which will be tough to fix.
  • MIXED: – Have to educate everyone on public api design

2) Develop for the product on a branch/fork. Separately deploy this branch to support the new product. Merge things back to the public master, carefully, as the features stablise

  • GOOD: – Can move fast and merge only the best version of ideas that worked internally into my public api. – Less chance of sloppy work getting into my public api contracts
  • BAD: – Two codebases. -Merge effort + risk things will never be merged. – more CI and infrastructure
  • UNSURE: Risk that people will develop more ‘powerful’ internal only methods which cannot be merged into public

3) Have secret methods on public api. Maybe requiring a secret token

  • GOOD: “Two APIs” on one machine and CI.
  • BAD: – Complex – Easy to add things like this, but hard to modify things – Hard/impossible(?) to setup auto-documentation like swagger 4).. ?