A technical founder’s review of API experiences— Trello

Laying their cards on the table…or uh…the board

This is the second review in the series of about 7 APIS. You can find my review of GitHub’s API here and JIRA Here. Over the course of the next few weeks, I will be continuing to blog about my experiences with a few APIs I have been using to build OverVue. The focus will mainly be around authentication and webhooks, Ruby and any 3rd party gems used. I will try and keep the reviews light on Ruby code or specific gem usage to make these as general to the API quality as I can. Some readers may find the reviews lack in depth down to the request-response cycle information, but I wanted to focus more on the integration and getting up and running with an API integration and aptly adjust the title to include “API experiences”. In addition to the Trello review here, I will also be reviewing Slack’s API, HipChat’s, Bitbucket’s, and Asana’s(I will link out to them as they become complete).

I am using the Trello API to collect card, board, list and checklist, creation and update events via webhooks to coalesce those events with Overvue channels and users. Providing insight into how a team, project or user is doing in correlation to the status and commentary to a report.

Working with integrating Trello’s API with OverVue was a mostly pleasant experience. The documentation is ‘pretty good’, but I feel like there can be some better ‘connecting the dots’, in some places such as using an app authorization AND a full OAuth handshake. The API works as described with no surprises or issues experienced.

Documentation

After a quick Google search for “Trello API”, you are greeted with a developer landing page and three main links to the “Get Started” guide, the “Pro” API docs and “Powerups”. Checking out the getting started guide is a quick way to get a feel for how the Trello API process works, and how to get going. Inside the guide is a link to get your application key, which will be used for authenticating users to your product, via Trello. However, the examples in the guide use the Trello javascript library and is not applicable to everyone’s environment. Additionally, on the page is a link to an API Overview and introduction.

Getting back to the actual API documentation, it seems to be documented fairly well. A list of all endpoints can be expanded based on main endpoint into its individual verb and sub-endpoints. Once one is expanded, you get a general URL structure, arguments, and example requests and responses.

Authentication

Trello supports full OAuth, but has seemed to be quite sparse on documentation on using the full OAuth process manually. This won’t be an issue for most, but if you need to use the authorization process on the backend and retain information about your code(account ids, etc), you will need to use the seemingly undocumented process.

I was able to find some documentation here and through the Omniauth Trello ruby gem. While this was sufficient for me, I feel this could be better documented within the Trello developer platform and while I can’t confirm my suspicion, I swear there used to be even a small paragraph about manual OAuth usage in the developer center. With the OAuth endpoints in hand(and gem/package in the language of your choice), you can just plug in your developer keys, and carry on with the usual OAuth song and dance.

API/Gem

You can find the unofficial, but ‘everyone uses it’ Trello Ruby gem here. Overall the gem seemed to work without much issue once you have OAuth access tokens stored for the gem to authorize with. There were a few methods in the gem that seemed to help out with the authorization process, but I was never able to get them to work as the GitHub readme is light on details and the ruby docs for the gem don’t describe all methods in depth. This isn’t an API issue, nor should be a deterrent for any developer.

Webhooks

Webhooks play an integral part in OverVue’s event integrations. Setting up webhooks allow the 3rd party services to contact OverVue endpoints to insert events into the database. The events are then sliced and diced into other resources such as channels. While the documentation for the endpoint to programmatically add/delete webhooks themselves was great, the information about the actual events is sparse or non-existent.

After much searching, buried deep in a guide was another link to a Webhook Guide. While this guide does a great job of explaining webhooks, how they’re added, how they are triggered, how they're secured and a very general sample payload, there was a lack of event listings, sample payloads for each event and information about payload attributes per event. This leaves the developer with two options: to try every Trello application action they can think of, or search google for a list of events, anywhere.

I did what any sensible developer would do and googled ‘trello webhook events’ and found a few packages/repos that had some sort of event lists they had built themselves. From there I hooked up most of the event types listed to be recorded in OverVue.

If anyone at Trello reads this, please, please, please at least list out the event types in your API/Developer guides. The cherry on top would be sample payloads for each. The perfect webhook tool would all replaying webhooks as well.

Lastly, Trello offers HMAC256 security on their webhooks to ensure the authenticity of the incoming payloads. This has become more or less an industry standard on webhook requests, but not *everyone* uses them on their request yet.

API Grade

In the spirit of the series of API reviews, I will supply a grade for Trello as well. Generally, it was a rather pleasant experience and outside of a few holes in the documentation that lead to just a few extra wasted hours it was straight forward and easy to use. The API itself looked to follow the REST standard pretty well. With that being said, I am offering the API Experience Grade to Trello of a…

B+

If you like this review or others, please ❤ and recommend! Leave a comment too!