CODEWITHSUNDEEP
apiversion-controlversionversioningsemantic-versioning
abhi
abhi

Reputation: 253

Should you maintain separate version numbers of your web-based interface and APIs?

Suppose you are developing a platform which has a web-based interface for its users and APIs for third-party developers. Something similar to Salesforce (or even Facebook).

Salesforce and Facebook, both platforms have normal web-based interface for its users and APIs for third party developers.

Ideally any API internally calls the same function which is being used by the web-based interface. For e.g. "Create a Project" button and "CreateProject" API calls the same "createProject()" function internally. So you can maintain the same version for both as in most cases they are tightly integrated.

Now sometimes you add a feature which makes you increment the minor version of the web-based interface but since you are not implementing that feature in API, API version should remain as is.

How do you handle such cases? Should you maintain separate versions of your web-based interface and APIs for your platform?

Upvotes: 2

Views: 237

Answers (2)

yogs
yogs

Reputation: 788

Do not publish core function directly via API, instead create all API functions as proxy functions and all changes in core functions will be handled in proxy functions.

Change public api version if there is change in API input/output.

This way you could achieve code re-usability and it does not increase public API version frequently.

Edit:

If you are talking about software version number. My answer is Yes.

Upvotes: 1

this. __curious_geek
this. __curious_geek

Reputation: 43207

It Depends. Because It is difficult to offer a conclusive answer to this question. But I would share some ideas and drill-down some scenarios to help at best.

I would suggest there should be two versions of the api. internal apis and public apis. At a caller's end, they would be two physically distinct apis/end-points so that the security policies and a of lot of other things can be done without exposing much information as well as without relaying any responsibility on code to handle the distinction policy based on who's calling from where as that may quite easilyfail.

It is ok if both versions of the apis consolidate down the line to some extent without involving any security risk but a separate team of expert engineers can design this consolidation to be seamless yet safe. It's a trade-off of between code-reuse and everything else. This is very subjective and can turn into endless discussion. But the software evolves very well as result of this design process if it is agile and iterative.

The apis should be externalizable and inter operable. If the project is very large, then different teams working on separate parts of the project will interact with each other's work using internal apis only. No hanky-panky. No direct data access. Only apis.

This approach will help you create awareness of what's being done in the project across all teams if the apis are discoverable which I personally believe is a very good thing for collaborative team work. In fact it also helps in re-usability. Testing becomes unified and automated. Every team will become responsible for their own work and hence it should be easy to address accountability.

There's more stuff that can go in here but I think this is sufficient at a high level.

IF allowed, I would also read this question as

"Should you have purely service oriented architecture or not ?"

And my answer would be, **It Depends.**Because It is difficult to offer a conclusive answer to this...

Upvotes: 1

Related Questions