I love the idea of API Driven Development (ADD). It provides great flexibility and by default makes your app developer friendly from the beginning. The challenge is that it's hard to demo an API without an application tied to it. The goal of this post is to help you get past the API design and creation phase as quickly as possible, so you can focus on creating killer apps and encourage others to build upon your exposed data. This tutorial should be especially useful for hackathons and prototypes.
With the APIary.io platform we’ll create documentation that your whole team can interact with and contribute to. Then, we’ll create a working version of the API using Python/Flask. To demonstrate the process in a tangible way, we’ll go through the process of creating a simple GTD ToDo list API.
First, we must define what data needs to be exposed via the API. My tool of choice for this type of planning is a mind map. Our Lead Developer Evangelist, Brandon West, has written a great post on Why Mind Maps are Awesomesauce. I am using square brackets to denote arrays.
Once you’ve defined your data, use the resource/attribute paradigm to group the data points. A resource is any item that will be referenced or acted upon. Each resource may have attributes that help define the resource. The mind map above demonstrates this visually. The first level of nodes are resources and the second level is attributes.
Now that we know what data we are exposing, we need to organize it such that we can create endpoints that developers can use. This is simply a matter of listing out the final URLs as demonstrated below.
/folder
/project
/task
/context
For the base URL, it’s good practice to use a format similar to api.yourdomain.com. You can then host your docs at docs.yourdomain.com and serve your developer community at developer.yourdomain.com. Reserve yourdomain.com for your marketing.
Now that we know the endpoints to build, we will use Apiary.io to rapidly prototype and begin getting feedback. In this example, I’ll only define the folder resource and its attributes. Go ahead and grab a free account if you want to follow along.
With Apiary.io, you first create an API Blueprint in markdown, then using their tools, that markdown is converted to interactive documentation, complete with a mock server. For our example, the following is the API Blueprint:
Here is the generated documentation and the mock server. Go ahead and click around and explore.
Now, let’s go through each section and understand what each piece of markdown is doing.
The FORMAT label is used to define the version of the API blueprint and the HOST defines the official URL of the API. The full details are at APIary.io’s GitHub.
Note that in many cases, you’ll have a heading before the resource called a Group, used to help organize related resources. In our case, we start at heading two (as defined in markdown by to hash tags). In square brackets we describe the endpoint. The curly braces are used to describe any parameters. If you have more than one, separate them with commas. Prepend a question mark if your parameter does have its own endpoint, such as in the case where you want to provide an operator on your resource. For example, you may want to have a limit parameter to define how many folders you want to return.
It’s good practice to separate and define the required and optional attributes.
After the attributes are described, we formally define the parameter and describe whether or not it is required and the data type.
Optionally, we can define a Model. Think of a Model as a template. Later in our API Blueprint, we can simply use the name of the Model and in the docs the Model name will be expanded.
To represent the retrieval of a list of your resources, use a Collection. You may want to add parameters that limit the results, such as a start and end date or a limit.
At this point, you can share the API with stakeholders and get some feedback before you start writing any code. If you have not been following along, check the results here.
Now that we have reached a “final” version of the prototype, let's translate that data to a functional API using Python and Flask. You can find the source code on Github and the steps to get the API setup on your local machine. Following is the Python/Flask implementation of the prototype we developed with APIary.io:
Finally, you will want to use Dredd to test your API Docs against your implementation.
This is only the beginning. If you want to go deeper, I suggest you check out the following resources. To get that last one, you’ll have to join our awesome team :)
I love the idea of API Driven Development (ADD). It provides great flexibility and by default makes your app developer friendly from the beginning. The challenge is that it's hard to demo an API without an application tied to it. The goal of this post is to help you get past the API design and creation phase as quickly as possible, so you can focus on creating killer apps and encourage others to build upon your exposed data. This tutorial should be especially useful for hackathons and prototypes.
