How the server's API are evolving and how to keep the backward compatibility.¶

Protocol Server upgrade policies¶

The server is evolving, but most of the time and unless notified, the changes are always backward compatible.

The authorized backward-compatible changes on the server's JSON api are:

1. Add new APIs
2. Add new optional parameters in existing APIs
3. Add new fields in JSON responses
4. Add new values in 'enum' types
   (enum types are recognizable in the fact that they are represented by selectboxes in htmlform)

The non-authorized changes are: (unless notified!)

1. Remove existing APIs, parameters or JSON fields
2. Remove values in 'enum' types

Client JSON response parser shall be tolerent to those changes.

For instance the fizlibapi (a java 1.6 client for android and other java platform) will handle those changes by doing the following when parsing JSON responses:

1. Ignoring extra JSON fields.
2. When parsing an enum and finding a unknown value, replacing this value with "SOMETHING_ELSE"
   SOMETHING_ELSE value is an enum values that is included in all enums and represent a value that could not have been recognized.

Other client libraries, iphone or windows phone, shall behave the same

How to handle extra JSON fields and SOMETHING_ELSE values¶

The following behavior is implemented to manage new fields:

1. On read operations, new JSON fields will be sent by the server to the client, but they will be ignored by the clients.
2. On write operations, new JSON fields are always optional. If they are not sent by the client, the server will:

1. Ignore the missing field on updates, leaving the older value
2. Use a default value on creation operations

The following behavior is implemented to manage new enum values:

1. On read operations, new enum values will be sent by the server but understood as "SOMETHING_ELSE" by the client. Depending on the cases, appropriate behavior shall be implemented on the client:

1. For new record types (for instance for a new wall messages type, the wall message is unreadable by the client, they are useless to them because they just simply cannot be displayed if the type is unknown), the entire record shall be ignored by the client.
2. For cases when the number of returned record is important (for instance wallget and wallnotification apis), the client must use the filter provided by the api on types, to ensure the correct number of record that the client can understand is returned.
3. For new enums that are merely a qualifier (for instance, places have a type that can be 'doctor','work','school',etc. They are actually handled has a string by the clients to be displayed or chosen), then the client shall display "OTHER" to the user (or "UNKNOWN", the actual text depends on the usecase) .

1. On write operations, if the client sends "SOMETHING_ELSE", the server will not update the enum.

• This comes handy when the client is displaying "OTHER" to the user and the user is not changing the type. In this case the information is not lost on the server.

Heavyweight/mobile clients cache policies¶

Server may changes opaque attributes in the returned data (such as Identifiers, media URLs, etc) without notice. As a result, client shall cache information only following the sync api. With those apis the server is able to control whenever client cache is obsolete.

Caching policies MUST follow sync-api