The quest for a better API

Hi DougS,

Actually, it doesn't really matter if you think "vc" is a misfeature or not; the thing that matters is that Lithium refuses to make changes to the API because they would break existing code.

Even adding a new field is considered a breaking change.

As a result, we have to do a gazillion extra calls to get around API shortcomings.

If API details were frozen for each version, and "vc" is not used, there is no way that changing the API would break existing code, since existing code has no way of using the new API without the code being changed to use it.

My thought is that Lithium should be able to make changes to existing calls, as long as those changes don't remove information returned (so we could add additional data to existing calls).  However, I've been informed that we have at least one customer who is parsing the entire XML returned by different REST responses in a way that will break if new elements are attributes are added that the parser they use doesn't recognize.  I think it's for this reason that we won't add additional data to any existing REST call responses.  

I agree with you that we should not be hindered by this problem and should create more versions of calls where needed.  As long as we don't change the configuraiton for "vc" (which stands for "version configured", not "version current") so that it points to a version later than v1, all calls that use "vc" will continue to point to v1 and will not break when we release the new version.

Hi wmertens -- Your points are well taken.  In order for Lithium to evolve the REST API, we need to use versioning.  If adding a field, for example, would make a call more useful, then we shouldn't be prevented from doing so because it might "break" the call for someone else.  We should create a second version of the call with the new field.  

But, we also need to be careful.  If we create new versions of a call every release (an extreme example), that certainly gives us a lot of flexibility, but it's very difficult to maintain and complicated for developers.  You'd potentially have to look through tens of versions to choose the right one.  Practically speaking, there is a middle ground and we're discussing what that would look like.  No concrete plans at this point, but we agree that versioning is important.