Server side API versioning

Background

When building a web app, the server side code and the front end code can easily be kept in sync by simply pushing both sets of code into production. However, with mobile apps, the front end app version may not be updated by the end user, leaving the system vulnerable to breaking changes. For example, what if you change a server action to now require a new GET param…the existing apps don’t know about this and would quickly break.

API versioning

The backend of a Wappler project is really just a set of API’s. To keep our front end app in sync with the backend, versioning of the API is needed.


Back-end setup

Server action folder structure

Rather than creating server actions in the root of the structure, first create a major and minor version folder. The example shown here has shows API versions 1.1, 1.2, and 1.3. You can of course use whatever structure you’d like.

Screen Shot 2020-03-10 at 5.09.37 PM

Preload

The first thing your app is going to do, is execute a “preload” server action which does a lookup of your app version in order to get the corresponding api version. This allows you to change the api version of an app without having to push a new app build to the stores.

This preload just does a quick db lookup and returns the results

Endpoints

Your endpoints are then placed under your minor version folder and are the same as without versioning.

Screen Shot 2020-03-10 at 5.15.34 PM

Creating a new version

Simply duplicate the latest version, and give it a new minor version number, or create a new major version, etc.

Screen Shot 2020-03-10 at 5.17.14 PM

Build Table

The Builds table (used in the Preload) just maps an app version number to an api version. You can see this also allows you to redirect any mobile app version in the wild, to your dev/staging/production environments just by changing the build table entry.


Front-end setup

Preload

In the mobile app there is first a call to the preload, which on success, triggers the other server connect actions that load any startup data. This gets the path to use in all other server connect actions.

Server connect properties

Each server connect action will how have a typical URL attribute, but we are going to add in the code a dynamic url attribute as well. The static URL will allow Wappler to continue to show the proper data bindings, while the dynamic URL will be called during execution. Again note the noload attribute as this action will not be called until preload is finished.

	<dmx-serverconnect id="app_load" url="https://dev.yoursite.com/dmxConnect/api/app_load.php" dmx-bind:url="https://{{pre_load.data.config.api_server}}app_load.php" site="Site-Backend"
		 noload="noload">
	</dmx-serverconnect>

Each server action needs the same modification which currently must be done manually…this is really the only addition to any ongoing workflow. You just have to remember to do this! If you don’t it will likely show up in bad data results, etc. triggering you to fix.


This will greatly reduce the breaking changes introduced into previously published app versions by making changes in your back-end AND provides flexibility in directly an app version to the desired back-end data.

19 Likes

Ken, what a wonderful post! I am sure the whole community is going to benefit from your experience and wisdom in getting your mobile app together… Thank you! :slight_smile:

1 Like

Excellent post, @mebeingken. I suspect you’re the first Wappler user to finish a native mobile app so would you consider putting together a ‘getting started’ guide to outline the structures and methods for building an app? I tried it a while back but hit too many hurdles I couldn’t overcome but, now I’m way more familiar with Wappler, I want to go at it again but I’m still unsure of the first steps.

2 Likes

Great post, @mebeingken!
Could you share the experience on how you manage security for your API?
Do you create a token, or other mechanism?

Thanks Jon,

@Dave has some posts on setting things up for mobile, and it looks like my client will be going live with this project in a month so I’ll have some time for a write up or two at that time!

Would welcome your comments on this idea for API calls if you can spare a few minutes

1 Like

Hey Alex,

Will be adding security in this week and will update!

1 Like

Hi Brian…that’s a comprehensive post…must come back after coffee! :slight_smile:

2 Likes

Great article, thanks so much.

1 Like

Uh Oh…I discovered a flaw!

Long story short, the static URL doesn’t really work for data bindings when new the data bindings change across api versions. I guess a hacky solution is to globally search and replace to change to the current url so that data bindings are current.

So this solution is still valuable, but not as much. I hate having to remember things. :slight_smile:

This is wonderful article @mebeingken.

May be if there was a possibility to call another server action from the current one (this discussion - Invoking a server action from another), we could achieve this dynamic part on the server-side itself like this (replace redirect in the below image with “Call #serveractionfile”).

Supporting this out-of-the-box in wappler could be a great feature @George :slight_smile:

1 Like

Just wanted to understand what change in the server action is required here @mebeingken?

Just before that quote is a code sample. In that you can see there is the typical url parameter used while editing and there is also a dynamic url used at run time using the proper version of the api.

1 Like