This document was generated from CDN thread
Created by: Kenneth Rehor on 23-06-2011 10:26:57 PM
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
Subject: RE: API changes in upcoming MediaSense 8.5(3) release
Replied by: Chris Yeo on 13-09-2011 10:54:46 PM
In addition to what Ken provided, there are 2 more additional changes in 8.5(3):
sessionId parameter no longer allowed with getSessions API. We have modified the getSessions API to now require the client to specify a time range within which the request will be applied. The purpose was to apply some constraint on the number of sessions that such a request would return. Including a sessionId parameter actually limits the number of sessions to one (or zero if not found), which makes the time range requirement extraneous. However, adding a rule by which time range would become optional if a sessionId was specified would have made the API unnecessarily complex, especially since an alternate API is available specifically for this type of request. As a result we have eliminated sessionId as an acceptable parameter on the getSessions API, and clients including this parameter will receive an error response.
Recommendation:
Convert all calls to getSessions which include a sessionId parameter into calls to getSessionBySessionId.
------------------------------------------
Error response codes to change for some APIs. Several APIs currently return a 5xxx responseCode if the value requested is not found in the database. This is technically incorrect. 5xxx response codes are intended to indicate that the server encountered an internal error, but in these cases it is the client who issued an invalid request. In release 8.5(3) then, these APIs will return a 4xxx responseCode instead.
The specific APIs affected are:
- cancelJob
- deleteJob
- getJobById
- getJobResult
- getJobs
- addSessionTag
- deleteSessionTag
- deleteSessions
When these APIs return responseCode 5005, they will now instead return 4005. The response message, "Failure: Cannot find value in database." will remain the same.
Recommendation:
Examine your client code for comparisons against responseCode values in the 5xxx range, and make sure they operate propertly when the responseCode value becomes 4xxx instead.
===============================
Chris Yeo,
Product Manager, MediaSense
