Noah Mobile Versioning

Owned by Andrea Dennis
Last updated: Nov 25, 2020
4 min read



Since the Mobile API will continue to develop over time, there is a need for App developers to know which version of the Web API that their App is communicating with. 


Web API version

A Web API version is identified by a major and minor version number i.e. <major>.<minor> e.g. 1.1.



  • Breaking changes e.g. behavioral modifications - will cause the higher major version number to be increased. This should happen very rarely. Another type of breaking change is the end-of-life support for a specific version of the Web API.

  • Non-breaking changes e.g. extensions – will cause the minor API version number to be increased. Non-breaking changes are new resources or extending existing Responses.

  • If a remote host (the Noah Server) supports version 1.n the remote host will also support all versions less than n.

  • Over time, the support for old versions may stop when accessing the remote host through the cloud. Even if an old version cannot be accessed through the cloud, it can still be accessed locally.

  • The data returned from the discovery call has been extended to include the versions supported by the remote host. The versions will be returned as <1.n>, <2.m> etc. 

  • When calling the Web API the application must specify the version that the application is developed against. The version is stored in the request header identified by “api-version”. If the remote host does not support the function a NoahMobileFault response is returned with error code 60065.

  • In a reply, the version number of the Web API is stored in the reply header identified by “api-version”.

  • Apps must handle responses that are returned using a higher or lower version than the version requested by the App. This means that an application may receive less or more data than expected by the version that the App is developed against as the remote host always will return the data that match the version of the Web API. 

  • If accessing a remote host, that supports an older version of the Web API, through the cloud the response will contain the full response (the response in sky cloud may contain more data than the remote can provide) the App developer must neglect the data that not supported by the remote host Web API version.

In general an App developer must take into account that even though the App is developed against a specific version of the Web API, the App will properly connect to Web API’s with a different version and must handle this properly.

For example, strict serialization techniques can be unnecessarily intolerant of change. A more tolerant reader should only be concerned with data that it needs and ignore every other part of the response. This means that the majority of changes are unlikely to break the integration.
 

Handling responses correctly in Apps

When an App requests data via NoahMobile, the App specifies its own api version, however the response received by the App may be provided using a different api-version. It is very important that the app is very tolerant of the received data structures and can handle such responses.

The App should be able to handle the following scenarios:

  1. The App’s api-version is less than the received one of the received data structure.
    • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.7.
    Then the App must disregard all received properties that are unknown to api-version 1.5 data structures. This means that the App would have to ignore the ‘middleName’ and ‘Phone’ properties, see the Figure Below.

  2. The App’s api-version is greater than the received one of the received data structure.
    • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.4.
    Then the App must disregard all received properties that are not part of api-version 1.4 data structure. This means that the App would have to ignore the ‘zipCode’ property (See Figure 1).

  3. The App’s api-version is equal to the received one.
    • Assuming the App only has knowledge of data structures represented by api-version 1.5 or earlier and receives a data structure provided using api-version 1.5.
    Then the App can use all received properties.

Figure: Sample data structure evolving from api-version 1.4 to 1.7

Version Schedules

The general rule is that an API is supported for at least 2 years, and that it will follow the Noah version it was released with. The specific end of support will be announced in the Platform strategy document.

For SDKs a version will always remain available as a downloadable package. However, if it is beyond its end-of-life date it may rely upon APIs or methods which no longer work, so you should assume an end-of-life SDK is no longer functional.