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).. ?
