One of my absolute favorite all time tools is Trello, which is essentially a web application that digitizes the kanban board. As a Trello user, you have one or more boards, and each board can have one or more columns. In each column, there are cards. And, like a live kanban board, you can move the cards around between columns.
Trello is good enough to expose a RESTful API so that I can interact easily with it. I'm not going to go into a lot of detail on the particulars of the REST style of architecture here, as that's not my main purpose. But I will offer the useful way of thinking about REST that it's an idea of pairing identified resources with actions -- specifically, HTTP actions. Or, more simply, it's the idea of pairing nouns and verbs. And so, figuring out who the members of the Beatles were might involve making a GET request to http://somesite/music/beatles while adding myself to the Beatles might mean issuing a PUT request to http://somesite/music/beatles with a JSON payload containing my name. Pretty awesome, huh? I've always wanted to be a Beatle.
Alright, so let's use this REST API from Trello to get a card out. Trello offers a "getting started" tutorial, and that got the job done for me, but I think it could be explained more simply. They're aiming to get you started writing applications that interoperate in rich ways with their web application, but I'm just interested, for now, in getting back "toothbrush."
To understand what I mean, take a look at the screenshot below from one of my Trello boards, "Packing." I use this board when preparing for trips. I populate the "pack" column with stuff to put in my suitcase, "non-suitcase" with stuff like my laptop and Kindle, and "To Do" with things like "set the thermostat" or "water the plants." What I want to do here is thus dead simple. I want to get ahold of that toothbrush card via their API. That's it.
To do this, you need to be logged in to Trello and, obviously, you're not going to have my toothbrush card, but you can create your own board and card to follow along. Do that now, if you like.
Once you've identified a card for which to do this, you're going to need three things: the id of the card, an "application key," and a "token." What you're not going to need is to open Visual Studio or any other IDE, nor will you need to figure out some kind of REST client to build your request. You'll do just fine with your browser, as-is. We'll get to the REST clients and IDEs in future posts.
What was initially confusing when you're reading their "getting started" page is why you need a key and a token. Well, the key is for you as a Trello developer, whereas the token is your way of authorizing calls to your non-public boards (and most boards aren't public). To make it easier to understand, I could use my developer key to query Trello's public development board and I could also use it to access Ringo Starr's private boards if Ringo Starr issued me a token allowing this. So when it comes to querying my own board, I need a developer key, and I also need to grant myself permission with a token.
Make sense? Good.
Now, to get down to business. Navigate to the trello app-key page while logged in and you'll be granted your key at the top. That's the easy part. To grant yourself a token, you're going to need to work. Scroll down to the bottom and click on the link that says "Click here to request a token to be used in the example."
Once you click that, you'll get a pop-up requesting permission to grant the application access to use your account. Hopefully this drives home the idea of a token. In general, if you want anything to be able to interact with your Trello account, you have to give it permission via this token. Once you've done that for your own account, it's time to rock and roll. Now all you need is the ID of the card that you've created, which you can get just by clicking on the card through the application, like so.
With that id in hand, type the following into your URL bar making appropriate substitutions for the placeholders that are colored orange:
https://api.trello.com/1/cards/cardId/?key=YourKeyId&token=YourTokenId
You should see a bunch of JSON in your browser, outlining the attributes of this card.
And that's it. Without code, IDE or tools beyond the browser, you've successfully used Trello's API. Stay tuned for future posts, where we'll get into doing some stuff with it that's actually interesting.