Pivotal Tracker just announced the availability of their API V5 in public beta, starting August 16, 2013. The launch is justified because the application itself has run against the new API version for a long time now.
photo by John Fischer
The new API introduces several improvements, like the ability to get access to all project data, including epics. They also say that everything in and out of the API is now JSON encoded but the activity Web Hooks still POST information using XML.
Another improvement is that now errors are more consistent and informative. They don’t exactly explain how but I did a few tests and verified that, in addition to responding with the proper HTTP error code, the API also delivers information about the error itself:
- code: a textual identifier of the error, e.g., unauthorized_operation;
- error: a human readable representation of the error, e.g., “”Authorization failure”;
- general_problem: a human readable representation of the problem that originated the error, e.g., “You aren’t authorized to access the requested resource”;
- possible_fix: a text explaining a possible way to fix the problem and prevent the error from occurring again.
The possible_fix item really caught my attention because it’s not something that you see around very often. It not only informs you as a developer about how to fix the error but it can also be used on the presentation layer of your own application.
Overall, the new Pivotal Tracker API introduces many benefits and shows that the company is concerned about how developers consume it, improving UX in the long term.
Thanks for the write up, Bruno. One clarification – the activity web hook (in V5 format) does in fact post in JSON, we just haven’t yet updated the activity web hook help page. When setting up the webhook for a project, you can specify the old V3 XML format, or the new V5 JSON format.
Thanks for the clarification, Dan. Let me know when you update the activity web hook documentation and I’ll update the article.