The quest for a better API
Hi everyone, I added these two ideas: "API-first" development REST API versioning should be actually used I would appreciate your help in voting them up if you agree with them. Thanks...
Forum Discussion
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.
