We plan to make some small changes in the MediaSense Release 8.5(3) API, which are incompatible with earlier versions.  The purpose of this note is to give our partners advance notice of these changes, so they can ensure that their client software will not be adversely affected by these changes.  The recommendations below will allow client code to function properly no matter which version of MediaSense is in use.


API changes to reduce the likelihood and impact of non-scalable queries:

Limit=0 to be disallowed.  Many API queries allow you to specify paging parameters (limit=n&offset=m).  Currently, limit=0 means no limit; in other words the client will receive all matching records.  This can have a potentially negative impact on the performance of MediaSense.  In the future we intend to prevent the use of limit=0.  Specifying it will elicit an error.  The client should generally avoid requesting a large number of records in a single API call, but if it needs to it can always specify limit= a large number.  Additionally, the maximum value which will be accepted for limit is 1000.  In other words, the client cannot request more than 1000 session records in a single query.

Recommendation:

(1) If your application explicitly specifies limit=0, or a high number greater than 1000, you should modify it to specify a reasonable and appropriate limit instead.

Timeframe to be required in getSessions queries.  We are adding a requirement that all API requests which return a list of Session objects must be framed by a time range.  The getSessions request will enforce that sessionStartDate is one of the operands, and the only operation allowed on it is "between".  Operators "greaterThan" and "lessThan" will no longer be allowed for this operand.

Recommendation:

(2) If you call getSessions without a sessionStartDate operand, or if you call it with a sessionStartDate and a "greaterThan" or "lessThan" operator, reformulate the request to specify sessionStartDate with a "between" operator.

Timeframe to be required in wrapper queries.  In a similar vein, all of the session retrieval wrapper functions will require either a minSessionStartDate parameter or a maxSessionStartDate or both.  If either of those parameters is omitted, MediaSense will substitute a default which results in a 2-hour time window.

Recommendation:

 (3) Add minSessionStart and maxSessionStart parameters to all of your API session queries.  They will be ignored for now.

These measures obviously do not prevent clients from invoking very large and impactful queries, but they at least require clients to think about what they are doing.


API Changes to Consistently Represent Empty Objects

Any time you look for a JSON property which could contain an empty set (such as {} or []), you should also be able to handle the property being omitted entirely.  In the future, tags:[] and urls:{}, tracks:[], and participants:[] may end up being omitted completely.  In terms of the specification, these return values are currently specified as "required".  In the future they will be specified as "optional", and if they are missing they should be assumed to be empty.

Recommendations:

(4) Modify your code TODAY to tolerate these parameters being missing completely from the returned object; if they are you should treat them exactly as if they had been included, but were empty.

Updated API Version Number

The API version number, returned by the getVersion API, will be incremented to "1.2".

Recommendations:

(5) Client code should have no expectations about the API version number.

=======================
Ken Rehor
Product Manager, MediaSense