Versioning API best practice?

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:



Am I close?


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

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

Thanks Ben,

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.

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?


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.

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

There’s a very high-level roadmap at

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

Thanks Ben! These look great :slight_smile:


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?


@Kevin_Mcgahey - I’m getting to something similar. I want to have my API evolve as the data structure changes, while still retaining compatibility. I’ve thought of using views of concept clusters with the version number in them to maintain compatibility as the underlying tables evolve (eg, Users-3.2.4), but I’m unconvinced that’s a good idea because it would proliferate views.

Now that we’re looking at V3 on the horizon, Sven’s question still seems important - are we going to /api/v3? Is that vX available for me to use? And are there any good best practices for applying, eg. SEMVER to data apis? Bonus points for mapping to Google’s best practices on the topic.


@jraiche1 - Great question, this is actually prompting us to look further explore this and thank you for Google’s best practices. With DreamFactory 3.0 on the horizon we do not have plans to change the url structure to /api/v3 so nothing to worry about yet, but will keep you posted if we have it in our future plans.

1 Like