iOS consuming API design

Question

I am going to develop an iOS app for a web application. (The web app uses code igniter)

I am going to create an API Service that the iOS app will consume.

I am thinking of creating an api version, so when the web api changes, the iOS app will know.

Concerns:

• iOS app will need to be updated when web application api changes (unless I keep legacy api available..Is this a good option)
• If iOS app is updated when web app api is NOT updated this will cause a problem too

Should my iOS app specify the version of the api it requires?

• If iOS app api is less than web api: Display Message: Please update iOS app
• If iOS app api is greater than web api: Display Message: Please update web app

Is this best practice?

Should I make an api class for every version and extend the previous version and override methods when they change?

Example

ApiV1 extends CI_Controller
{
   function list_customers(){//Code}
   function saveSale() {//Code}
}

ApiV2 extends ApiV1
{ 
   function saveSale()
   {
      //New way of saving sale
   }
}

Also what happens if I make a change to the database structure where the v1 api will no longer work? (Example, changed the name of a database table?)

Answer 1

In general, you want to create a fairly loose coupling between your service API and your client. As a rule, there will be multiple versions of the client always floating around in the wild, and you want to force upgrades on users as rarely as possible.

A full rev of an API version is actually somewhat rare in web services, and usually only corresponds to significant changes to the data model, security model, etc. Allowing multiple versions to coexist may require some extra work on the service, but can be worth it to allow existing clients to keep working.

To that end, think carefully in the design up front about the "model" you're using as an abstract entity independent of the current client UI needs. (If you want more specific thinking around your particular case, you may wish to post a separate question about modeling your needs.) But don't worry too much about solving all of the needs forever in advance, because requirements will inevitably change.

Once you've done this, do prepare for the future by building some notion of versioning into the service API. Some things to consider:

1. An explicit version as part of the URL scheme or specified initially during e.g. auth handshake. This is a way to cleanly namespacing what the client accesses. (The former would result in explicit URL routing on the service, the latter would require more gymnastics to route after cracking an auth token.)
2. A known error response that means "this API call is obsolete", which an earlier client can recognize to tell the user that their client requires an update

On the service, your design can be as explicit as you note, with a controller with method overrides, but at a little higher level: the saveSale method is somewhat unlikely to behave very differently between versions. It would seem more likely to have a saveSale method in V1 that does the baseline thing, and then maybe e.g. saves some extra bit of data in V2. When that happens, the code might just have conditional branching if that extra bit of data is present. All of this is another way of saying that a service API doesn't actually change incompatibly that often. list_customers could return more information over time. That doesn't necessarily mean that your API needs a new version or that old clients shouldn't just ignore any extra information they don't need.

Re: your final question about database table names. Those may change internally, but you aren't required to map those explicitly to what the client sees. An API is a stable interface that should ideally hide the implementation details of your ever-evolving service.

You'll choose to rev the API when, as a whole, you decide that the overall picture of what the API needs to do is significantly changed enough that it cannot peacefully serve the needs of existing clients. You'll choose to deprecate and obsolete certain client versions when you decide that maintaining support for them on the service is causing you more headache than the install base is worth (a very business/case specific issue).

Good luck.

Answer 2

I do not know as to what best practice, however I would definitely recommend that your iOS app keep track of what version of your API it is looking for, and specifically request that version. For instance, a URL of '/api/v1/....'. This way When you update your API, you can simply up it to a different version ('/api/v2/...', and leave v1 alone for the iOS app to consume. Obviously you should display a message to the iOS user to upgrade (perhaps a meta field in your response) when a newer version exists.

This approach should allow you to continue development on your API without cutting off people who haven't been able to upgrade their app.

Update

Just one more thing; if you make a change that will make a previous version inoperable (such as changing table names, schema, etc), you should have a status code for that that your iOS app will understand. Something associated with the message 'This API version has been retired. You must update'.

I would also recommend a similar header (or something) when an API is deprecated (ie, a new version exists). Obviously continue to provided the requested information/actions, however a warning that the version is not supported anymore and that they should upgrade (or even triggering something in your app to upgrade) can be helpful.

Answer 3

I don't know if having your iOS app specify the version of the api it requires is good practice but, I would think it is a safe play; one concern though, if you frequently update your api then it won't be long before it becomes a hassle/anoying having to frequently update the app.

I would keep legacy method name(s) and add method(s) with a different name to avoid users having to update to new version of the app when you change the web api.

I would not create an api class for every version to extend the previous version of the api.

I would say changing the database structure would require changing/updating your api, unless you also want to keep legacy version of your table name or definition or data, which it is not feasible/practical/convenient in most instances/situations. In this case you want your users to update to the new app and api.

Look at this answer that points to a presentation of API design principles and practices.