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.