Versioning API best practice?


#1

Hi. I am wondering, if I create an API definition for version 1 of my app, and then want to make changes in future versions without breaking v1 clients, how would I version it?

One way I imagine this could be done, though I am surely not clear that this is the best and recommended way, is to create another app, and call that the next version?

So my app names would be:

appV1
appV2

etc…?

Am I close?

Thanks,
Mike


#2

What kind of app are you building? Is it a web app or a mobile app that users install on a phone / tablet?


#3

a combination of HTML5/Angular client, and then a packaged version in PhoneGap for the apps…

Thanks Ben,
Mike


#4

DreamFactory 2.0 will support API versioning where you can pass in the API version as part of the API call.

For now, my suggestion would be to set up one app (i.e. one API key) and have two services (or N services as you change features of the API). Make sure you never remove the previous versions of the API in DreamFactory. When you release a new API, update the app binaries to point to the new API. Old clients still point to the old API which you haven’t removed from DreamFactory. New clients point to the new API in DreamFactory. Both new and old clients use the same API key…but that’s fine since old client binaries point to the old API and new client binaries point to the new API.

This is a workaround for now. As I mentioned, 2.0 will handle API versioning in a better way.

Also, what is the API you are using? If you’re connecting to a remote web service, then having multiple API versions makes sense. However, DreamFactory’s auto-generated APIs for SQL, NoSQL, and file storage will be backwards compatible, so you don’t need to version them.


#5

Thanks Ben!

That sounds like a great workaround. For now, because I am in the beginning stages of a new app, I don’t have legacy APIs to worry about. I asked this question because I am thinking into the future.

Do you happen to have any idea about the release of 2.0?

Cheers
Mike


#6

2.0 will ship in Q1 2015. We don’t have a firm date yet for the production 2.0 release, but we’re shooting for a beta release early to middle of Q1 next year.


#7

Thanks Ben! Would there happen to be a feature document for 2.0 somewhere to see?


#8

There’s a very high-level roadmap at https://github.com/dreamfactorysoftware/dsp-core/wiki/Upcoming-Features.

There are many other smaller features and bug fixes coming up as well, some of them related more to architecture than visible features.


#9

Thanks Ben! These look great :slight_smile:


#10

Hi,

any news regarding API versioning with Dreamfactory?

In current DF versions (DF 2.0+), the URL to the REST API contains “/api/v2/”. The version part is passed to the event scripts (and I guess to the service scripts as well).
So, it would be easy to rely on that version parameter as disriminator in the scripts. Is this correct? Or is the intention behind the version number in the path to have an option for DF itself, to be used in the futuire to upgrade the DF REST API itself?

Best,
Sven