Article

ADD and You

ADD-Blog-Post-Image-2

API Driven Development (ADD) is quickly becoming a popular choice and we understand why. ADD is a great process for creating a single page web app where API is at the head of your application because it starts with the API. Then, all aspects of the app are developed concurrently. In this article, we will quickly explain ADD and walk you through a typical setup.

In order to get started with API Driven Development, you only need to know: JSON, REST, and MD.  You might be familiar with the first two but wondering what MD is—it means Markdown and it’s used to write the API Blueprint.

We are not using your favorite programming language because we will be building an API Blueprint that is separate from your code for better scalability.  We can pick up this blueprint and quickly run a mocking server from it, or completely rewrite the API in a different language and still use the same API docs.

Writing out the API documentation is the first step in this process. Similar to building a bridge, blueprints always come first so that all of your builders can work concurrently towards the same end result.  Imagine building a bridge without first creating a blueprint? There would likely be many parts that you would have to go back and change along the way to achieve a sound finished product.  We don’t want to have to go back and rewrite code or change the API responses once things get moving; it would be a waste of time and money.  So, let us get started.

 

API Blueprint

In order to do this, we simply start typing out markup.  We follow the API Blueprint schema in order to allow our other tools to parse it correctly.  This article is about ADD and not API Blueprint, so I will only quickly cover the basics now and touch on some of the other features later.

The first line represents the version of API Blueprint we will be using.  Then, we can clearly see that there is one endpoint /v1/foo/ that accepts and responds with JSON in the form of a GET.  If you want to check out all of the API Blueprint 1A version you can go here.  In the Real World, you will have more responses than just 200; so, they would also be listed below under the endpoint (for instance: 201, 400, etc.)  When marking each of the responses, they are also given a body. 

Again, the markup is very straightforward and now we have some context.  One more thing with API Blueprint, I suggest you lay out each endpoint in its own file so that when you start structuring all of your endpoints, each will have their own API Blueprint MD file.  This allows for easy removal, updates, and overall directory sanity.  In order to include each of the endpoints, you will have a single blueprint that calls in all of your other endpoints using the below syntax.

Validation

Now that we have started to write some good API Blueprints, before submitting it for code review, we should validate it.  Validation can come from a few different sources that will help you accomplish what you want.  Just like you validate your javascript and CSS through something like JSHint or CSSLint, you have web-based options and CLI options.  If validating online is your style, you can sign up for a free account here (app.apiary.io) and validate your blueprint in real time.  However, how do you tie that into your build process?  To do that, the CLI option is going to be your best choice.

CLI validation can be done using Apiaryio’s tool dredd.  Dredd allows for many of things, including API Blueprint validation.  

The above will quickly reveal any blueprint warnings and errors that you might receive with your docs: you need to use standard tab spacing; your API Blueprint logic does not make sense; etc.  Dredd also allows us to do more, but for now running it in dry mode is all that is required.

Build User-Friendly API Doc

Now that you have finished writing your API Blueprint, you can quickly generate a beautifully styled static HTML so your team can better digest your API. 

Aglio is a great tool to do just this!  Personally, I went with a gulp plugin version of Aglio since it fits into the preferred task manager script: `gulp docs` will generate the current document static html file.  In case you were wondering what this will look like, you can quickly view this for a sample theme.

Mock The API

You now have a fully readable document file. But what good is it if you can’t have your other development teams test their calls with it?  Well, they can test their calls in theory, but that is not good enough.  To get a mock server running off your API Blueprint, you can use drakov.  Drakov allows you to mock out your future developed API server.  This way, the front-end side can get a better feel for how the server is going to respond, as well as actually make RESTful calls.  This allows the other client-side teams to work at their own rate, but still come to the same end path.  Using a mocking server also allows you to delay responses, and proxying to already developed endpoints.  The mocking server can be run locally on each developer’s computer, or in a shared network environment.

Testing

Now that the front end has been set up using the mocked API server, we can now start writing the actual API code.  Since we will be driven by our original API Blueprint, we need a way to constantly check back and make sure our endpoints are lining up. To do this, we can simply use dredd again to send our API Blueprint data to the newly created restful endpoint.  Dredd will do a quick validation to make sure that the newly created API endpoint sends all of the correct responses.  This then allows us to check back with the blueprint to make sure we are on the right track for success.  Testing against the API Blueprint is not suitable for writing unit tests, since testing against the API Blueprint only allows us to verify we are on the same page as everyone else, not that the actual API endpoint is saving data to the database.

Conclusion

Now that your deep dive is over and you have begun a unique exploration of ADD, I hope that your CDD (Cowboy Driven Development) or FDD (Fear Driven Development) days are over!  Or, that you can at least take a look at another way of doing things rather than the traditional TDD approach where other parts of your team have nothing to work on until everything is done.  Writing a bunch of code without a clear testable roadmap for all teams does not set you up for the best outcomes.

I hope to have encouraged you to write out the full API document before you start coding single page web apps, since it will give everyone a great roadmap before they begin the long development journey.  Plus, why waste your time and money developing something with no clear blueprint for the end result.  You don’t want anyone to get lost along the way!

team-stephen-dunn

Stephen Dunn