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

2 Answers 2


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.

It's not.

Really you have no choices here. You want to add functionality to your system. You have a public API. If you change the underlying system you will either break the API or not regardless of whether you make the new methods public; and having extra private methods isn't really an option if you want the public API to be fully functional.

Implement your new features a beta version, publish a non beta when you are happy that its complete. Remove the beta and support the old version.

  • So basically always do it to public API standard? What do you mean by "beta"? That's something I never deploy to prod right. So you're telling me to feature branch my stories, play around on a test environment, then make sure they are up to scratch, and then deploy them.
    – Nathan
    Jul 25, 2019 at 13:09
  • a beta version is a published version with no warranty
    – Ewan
    Jul 25, 2019 at 13:22
  • Right. So it's in production then? I have two deployed versions. So kind of like option 2?
    – Nathan
    Jul 25, 2019 at 13:42
  • you are always going to have multiple versions of an api live at any given time. The only difference here is that by saying your latest version is a beta you are saying it wont be supported as new versions come out. so you publish v3.1.344-beta and when v3.2 comes out you remove the beta one. where as you keep v1.x and v2.x up for years to support users who havent upgraded
    – Ewan
    Jul 25, 2019 at 13:47
  • 1
    versioning is a differenet thing from your branching strategy
    – Ewan
    Jul 25, 2019 at 13:48

An API being public isn't the issue. It's how widely it's used. You want to make a breaking change? Fine do it. Now go fix everything you broke! Do that before you pass this to me. Wait, I had things using your API. Fine, you fix em. Wait, we have 100 users of this API out in the field that have written custom code against it. Well hell now it's worse then public. It's published. You gonna rack up your sky miles fixing this or deprecate and think of new names?

To make breaking changes to a published API you had better not be beholden to those that use your API. Some aren't. Notice how Chrome and Firefox keep breaking your plugins?

Changing an API always has consequences. You have to look at the situation you've inherited and predict the situation you're creating.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.