Using an API, and my astounding lack of Ruby knowledge

So I actually did a good deal of real world API learning at work today. We offer web to leads capabilities and a free and open API for our customers, and while I understand the w2l enough to help people with questions, the API has always been shrouded in a veil of mystery to me. This is one of the main reasons I veered off my HTML/CSS course to come and spruce up my API skills.

I had a customer who was looking to find a record in their account, and then set one of the date fields for it. Using apigee, I was able to do the following requests. To GET information from that record, they need to do something like this:


So what does this mean? Basically, it’s a call (which apparently is another word for a request) asking the server for information on the deal. The /deals/5132932 is using the deal’s unique internal id number, which we give to each deal entered into our system, to tell it which deal we’re looking for. I believe the .json is telling it we want the response to be in JSON, and finally, the api_key section at the end is identifying us, the client, to the server to give us access to the data in that account.

Now, they wanted to write to the closed_time field for that deal, which is when the deal closed. To do this, they also needed to set the deal to its “Won” stage, and set the probability of the deal closing to “100%”. This is what that request looked like:


So it looks just like it did before, but now that we’re using the PUT verb, we’re telling the server to update information on that record rather than retrieve it for us. For each part we needed to update, we would add:

“&deal[thing-to-update]” and then set that equal to the value we were looking for.

It felt really cool to actually put what I’ve learned into real world practice, and even better knowing and using the correct terms for things.

Today I also started the part of the codecademy course where you actually use the twitter api.

First thing they had me do was register a new application with twitter, so that I could click Create my Access token, to get my consumer key, consumer secret, access token and access secret. Can’t wait to fin out what all these actually do.

At this point and on the next example I hit a crossroads. I feel like my ruby knowledge is not nearly up to par to move forward with this, and that seems like a prerequisite here. At the same time, I don’t want to veer too far off the HTML/CSS path I started, as I feel like those are the heart of all websites and I want to understand them very fully and not forgot the details of what I’ve learned.

So, while I’m proud of what I’ve learned with the API stuff the past week and a half, I believe it’s time for me to spend a week back in HTML/CSS land. I feel like it will refresh and reenforce my knowledge there, and then I can move onto the Ruby tutorial with more confidence.

API responses and WTF is UTF-8

As always, most of this is taken from codecadamy’s awesome course on learning ruby and the twitter api.

The response you get back has a structure, just like the request does. It’s made of three parts:

A response line, which includes one off the three digit HTTP codes.

A header, which includes further information about the server and its response. A good example is when it tells you the what format the response will be in, like XML with the utf-8 character set.

The body, which contains the text of the response, either in JSON or XML.

I think I can understand which part is which a bit better for this example than for the request one, but that may be because this example is more clear.

response anatomy

Quick aside, I always heard about UTF-8, especially where I work when we were having issues with foreign characters, and never really understood what it was. This article did a good job giving me a gist of it. Basically, prior to it a lot of people used ASCII, which had the ability to store a certain amount of characters (like 256 I think). 32-127 were for the normal english alphabet, but then from there it could be whatever, and lots of people put lots of different things in there. Unicode (aka UTF-8) was a different way and concept of storing those, which allowed for a crazy amount of characters to be stored, hopefully covering any languages and their character requirements. It’s important that this is set for a page, in a meta element and as the first thing in the header element, because if it’s found later in the HTML, the site will stop and restart its reading of the code in that character set.

Ok good talk, back to API stuff.

Parsing XML

XML stands for Extensible Markup Language, and is very similar to HTML. They both use tags in angle brackets, but the big difference is that XML allows you to use tags that you make up, rather than just the standard ones from W3C, aka the World Wide Web Consortium.

xml text

xml request

Parsing JSON

JSON stands for JavaScript Object Notation, and is an alternative to HTML. The name comes from its data format, which resembles JavaScript objects, and is often more succinct than the equivalent XML.

json text file json request


So when you do an API request, the response can be in XML or JSON, but the only way to know which it will be is by reading the documentation of the API you are working with. The documentation is key for any API you use, as it tells you what the API expects from you when you send it a request and what you can expect from the API when it sends you a response.

They had me do a practice request to check the status of a website (they had shown how to do this at the beginning of the course), and I was actually able to do it! The hints were definitely helpful though.

Screen Shot 2014-02-05 at 7.58.28 PM

After that and some other questions, I finally finished this course on how to use API’s with Ruby. Fuck yeah! Next up, time to actually do the twitter project.