This week I worked on one of the more complex API endpoints: the subtitles resource. The reason for the complexity is the atypical output format. Normally API endpoints return an object that’s encoded into JSON (or XML, YAML, or something similar). The subtitles resource follows this pattern, but it also allows users to get the subtitles as straight DFXP, SRT, Web VTT, or any other format that we support.
This leads to a lot of weird corner cases, like what if the user requests DFXP, but there’s an error with the request. There’s no way to encode that error as DFXP, so what to do? In the new code I just used JSON as a fallback. I think the old code did the same, but I’m not really sure.
Anyways, that endpoint is complete and live on production right now. I’ve said this pretty much every week, but again if you write API code I urge you to check it out — especially in a browser. One of the big wins from the API change is browsable API endpoints, and I it’s especially nice to use with the subtitles resource. Try sending actions along with the subtitles to simulate a user hitting the publish/save draft/approve/send back buttons in the editor. You can get to the subtitles API endpoints by starting with any video (https://amara.org/api/videos/<video-id>). Then following the links to to get to the subtitles.
Oh yeah, the API documentation should be building again. There was an error from a change I made last week, but now it’s up-to-date again. You can check it out at http://amara.readthedocs.org/en/api-refactor/new-api.html
