2.10 Documenting Your API

Documenting API's can be quite the hard task. I mean, if you want someone to consume your API you need to have very good documentation. At least I would like to have good documentation so that I could take the maximum advantage of your application, right? So what can you do to accomplish that? Well you can use many different documentation tools of course. Maybe RDoC or even YARD. But I have a better solution. I want to introduce you to Apiary. Even though the name looks funny, it's actually a pretty powerful tool. Essentially, it allows you to develop your API documentation. It has some sort of a blueprint specification that sits on top of Markdown, and that alone makes it a lot easier to document. But since it has a special set of features in the spec, you will be able to construct powerful documents. Either create a new account or sign in with either GitHub or Twitter. I'm gonna start by signing in with GitHub. And once you're there, you'll be able to type in your own API name, so I'm just gonna call it Tutsplusgemstaruant. There you go. I'm going to choose to create the API right away. So just click on create API. There you go. Now this is a demonstration of a document, this is the code side, so the Markdown syntax, and on the right side you will have the actual document being previewed. I'll give you a link in the show notes for this link right here. So if you check the blueprint syntax here, there's a great tutorial on how to use this blueprint syntax. But for now let's start by creating two specific scenarios. Let's start by removing all of this, because I really don't want that, at least as of now. I want to change, for example, the host which in this case should be let's see, a localhost:3000. I know this is pretty awkward to specify a development environment. But you should change this to whatever place you have your API in. Now let's also delete this line of code, and now for this I can just type in any description I want. This is basically a Markdown format. So I can type in, for example, something like this. There you go. Now, let's continue on with the two specific scenarios I was talking about. The first one is listing all of the orders. And the second one resembles the process of creating a new order associated with a specific table. So let's start by the process of listing orders. I'm gonna create a group called List orders, for example. As I'm typing stuff in, I will get a preview on the right side. I'm gonna start by providing a URL here, or just right here is the URL that's going to be a parsed into the document. Actually just type in a second degree header. Now I can type in a description as with any other document. I can type something like, This URL will retrieve the list of all orders. Now, what about the details around the request? What can I do exactly? Well, for starters, I can type in a response header like so. If I include a + and then a particular token, in this case Response, I will get a possibility for the kind of data that will come from this request. From here I can type in two tabs or eight spaces to provide a code sample. Let's try and represent an array. Each different array will have, for example, an order object. So the first one should be something like an id. So id, and it will have the id of 1. Then it will have a name which could be my name. Then an email, let's add in the quotes, this is very important. And maybe the table of representation. Let's create that representation right away. For example, id equals 1, and with the number of seats. I know I forgot the double quotes, let me just fix that really quick. There you go. So this is a possible representation of the response that we'll get from calling /orders, assuming you are using the normal JSON adapter, either with or without the active model serializers gem. I think this is the default one without the gem. So depending on what you're using, you might want to document this really well. Now let's stick with this for a second. This is a rather valid document. We have a header, which matches the title of the document, and then we have a second degree level that will describe this particular URL. So when I do this, I can choose to scroll further down below. You will see the default header, but I think that I'm missing something. Oh yes, I forgot to add in GET /orders. And now you will see List orders, that's okay. And now I get this special item that I can click on. Notice the description here, and if I click on this one, for example, I will go straight to some more developer friendly documentation. So I have a get request with the URL that's on top with /orders. I can choose the production environment. I can choose a mock server or something like that. And I can choose the program in which I can actually call the API. So if I use cURL right here, you will have an instruction that basically equals or matches what we've been doing all along. Just call the cURL command with the URL, or if you want to choose anything else, let's see a Python script, or a Node.js script. It really depends on the library that you're trying to use. There's one in Ruby as well. So let me just stick with cURL, cURL is the simplest one. At the bottom you will see a response and the appropriate status code here. So you will see the exact specification that we have here, although it might be just a little bit better formatted, if I say so myself. So Apiary takes care of that very, very easily. Because this /orders doesn't have really much to say about it, we're just gonna leave it like that. Now, let's focus on another kind of URL. Let's create another group called Create order. This one will be a POST request, and then it is going to be this URL in specific, let's see, table/1/orders. Actually this 1 we're going to replace it with a variable called table_id. Now as you can see, it is already throwing an error, or a warning. We need a response from this because that's the way that it's supposed to happen. So let's quickly type a Response 200, and by the way, let's just add in a small description. This URL will create an order for that table. Something like that will do just fine. Now as far as the 200 Response goes, we'll basically need to create something of the like. I'm gonna copy this block of text, there you go, just going to reinvent all of this. Let's see what else we need. Well we know for a fact that if something goes wrong, we will have a 422 status code. So why not copy this header here and paste if right at the bottom. But lets change the response code. This response 422 will have a similar structure, but instead of representing an object, it will have, I think a message should be the thing. I can type and example message here. Something was wrong. Now with this new response block, and if I choose to go back to the document. Let's scroll further down, you'll see Create order, and here I can click on it. And when I do, I will see that it is a POST request with a URL, and then the respective path. In here, you will notice that we have --request POST and then the remainder of the path the whole URL. We will have two different kinds of responses, 200 at the top and 422 at the bottom. So the user will know that indeed something is wrong and we will have a different alternative for unsuccessful case. There's only one thing missing from this Create order documentation. And that is, what kind of parameters should we send to this request? After all, it is a POST one, so most likely it is expecting some sort of parameter structure. So what better way to do it than to specify the parameters, like so. Apiary will recognize this, and we can type in here whatever parameters we are expecting. So, I'm expecting an order parameter which is going to be a Hash. Actually, it is not a colon, but rather a dash. So as you type, you will see the changes reflected in the document. We have an order, which is going to be a hash, and since it's a hash I actually need to type in something else. For example the name which will be, let's see, a String and also an email which is also going to be a String. Now let's just wait a bit until the documentation is updated. And there you go, it might take some time until you see the changes, it really depends on your connection. But let's try and improve this list of parameters a little bit further. I want to give some more details around these parameters. In this case, I wanna say that the name is The customer's name and the email is also The customer's email address, for sending the receipt, for example. I think this is a very important piece of information because it actually has some use. So the developer knows what he's dealing with. So, for sending the receipt. Now you will see the name and email being jotted down right there. And from here I think this is a much better choice. So we know that we have an order, a name, and an email right next to it. Now if we go to the request, you will see that no data is being represented as an example. Let's try and do that by creating one more piece of information. I'm going to call it request, and I'll pass application/json, because if I do this, you will see a major difference. See the header right there? You will know for a fact that you'll need to pass in this Content-Type. Now as for the parameters, I can create an example here and try to mimic as close as possible whatever's on the parameters side. This block will only refer to those variables for documentation purposes. This one is actually the example that you'll need to submit in order to perform the request. So I'll create an order category here, and inside we'll have a name. Let's see, my name and then the email address as well. So let's try and put it down here, and there you go. Now watch as I try to cycle through the request. And there you go, now you can see data-binary, you can jot down the content directly into curl. I personally like to use a JSON binary, but if you don't have that chance, maybe you're trying to send the request yourself, then it's probably best if you do something like this. Just shove the JSON content directly into the option and you'll be good to go. So this is one example to send parameters and create a solid example on how to use your API. Remember that depending on the tool that you're using, it will always reflect the changes. The fact that we're using a specification for declaring our document, each different library will be able to resort to the document and for example in the case of Ruby, you will have the values right there. [LAUGH] Disregard this. That's still to be updated. But you have this for example, RestClient application, that takes the list of values and the headers, everything into one single response. The documentation is parsable by Apiary, which in turn generates examples on different frameworks and languages. So regardless of you using one tool or the other, the specification is there. So you won't have any trouble porting your document to different platforms. I think that Apairy is definitely the way to go. With one single document, with a solid documentation blueprint, you'll provide the best example for your customers, for your developers. If you want to preview your changes live, just click on documentation. Let's save and publish first, and then click on documentation. This is the final aspect of the document. This is what the developers will see. From listing orders, creating order, and really anything that you want. If I choose to list orders, I will get the document on the right side with all of the examples and parameters, as well as with the create order. Everything is in here, which makes it awesome, and really easy to deploy your document.