Search This Blog

In my daily life as a programmer I come across problems. This blog, is where I record them (and more importantly their solutions) so that I can dig them out in the future. I hope it might save others some problem solving time too.

An Introduction to Apiary

While exploring what tools are available for documenting APIs, I came across a plucky startup from the Czech Republic called Apiary. Apiary is an API authoring and collaboration tool, that encourages UI first like design - except for APIs of course. In fact, document orientated design might be a more accurate moniker. You can write your Api in a structured syntax, and then publish that API into beautiful HTML documentation. You can collaborate with your colleagues, and customers alike, inviting them to give you feedback before you ever write a line of code.

Apiary aims to be the Github of the Api documentation space. It is a typically lofty goal from a startup, but from what I've seen so far, they have every chance of achieving it. Just as Github built on top of open-source tools, so too does Apiary with their own open-source initiative: API Blueprint. API Blueprint is an open source standard and toolkit for defining and parsing API documentation.

Blueprint Syntax

There are currently two syntax standards in play: the old and the new. When I created my first API last week, the starter sample text was in the old format, but checking again today, that appears to have changed.

The Old Syntax

The old syntax is (obviously) on the way out, but I want to mention it here to save you any confusion if you do come across it. Markdown syntax is allowed to add formatting in comment/description areas. An complete document would not be a valid markup document. Actions were defined with the help of the < and > characters, which elegantly illustrated the direction of the communication. Here is a example of how to define such an endpoint/action:

The New Syntax

In the new syntax, the entire document complies with markdown syntax. Reserved words are used to extract additional meaning from various parts of the document (headers, list items, etc.). One of the nice things about the change to all validating markdown documents, is that Markdown aware services such as Github will now render them in an aesthetically pleasing manner. The new syntax looks like this:

Like XML (or indeed Erlang), documents written in the version 2 syntax must have their first line be

FORMAT: X-1A. This will ensure the correct parser, and validator are used. If you forget this line, you might find your document being the subject of incomprehensible validation errors.

Blueprint Tools

There are a number of Api Blueprint tools that are essentially the reference implementations of the standards. The tools and the standards are open source so others can (and most likely will) create additions and variations to the tools currently available.

Snow Crash

Snow Crash parses Api Blueprint documents to produce a more machine friendly representation of their content (JSON). You can then take this representation to do all kinds of automation magic depending on your needs. Check out the Snow Crash Github repository for more info.

Dredd

Dredd is a great example of what you can do with the machine friendly representation of your API. Dredd will take your API documentation and use it to create a series of tests which it will then run against an end point of your choosing.

I'm looking forward to taking Dredd for a spin, but I'm not in a rush to dive into the code just yet.

Comments

Post a Comment

Popular posts from this blog

Whether you checkout Twitter or any of the other uber popular web apps, you will find dates displayed are often in a very user friendly "from now" format. Examples of this format are "Just now", "A few minutes ago", and "2 days ago". In these three examples a date value is displayed as an approximation of the difference between the absolute date value and the current time. This "from now" format could be applied on the server, but it is generally better to apply this on the client side via javascript so that it can be continually updated to reflect the every passing time. 2 javascript examples I've come across for applying the "from now" format are John Resig's lightweight pretty date library, and the other is more built-out Moment.js. In this post I explain how to apply a sliver of the power of MomentJs in an AngularJs application.
AngularJs is a delightful Client side javascript framework. One of its features is ca…

The one thing missing from the great text editor that is Mac Vim is a project / file explorer side bar. Competing text editors such as Sublime and Text Mate have one, so why not MacVim? It doesn't seem like it would require too much additional work of the developers. Reading through debates the community has had on the issue, the reason appears to be the elitist and idealistic nature of the Mac Vim community. Please don't read that last sentence pejoratively; these guys are purists, and very good at what they do. There were quite a few in the community who believed NERDTree was more than enough for any code jocky's needs, so I decided to checkout what all the fuss was about.

I use pathogen to manage vim plugins, and it is especially useful in conjunction with a public source control system like github. Once you have pathogen installed simply pull the NerdTree Github project to your vim plugins directory.

Introduction
There are a number of different functional test frameworks that can be used with Grails. Each of which can be incorporated into the overall test infrastructure of your Grails app by including the relevant plugin:
Canoo WebtestG-FuncGebSelenium-RCWebDriver
Grails doesn't hold any opinion on which one to choose. This is fair, and gives developers choice, but it can also be a headache; one has to make the choice of which framework, and also do the necessary setup and configuration. The functional test framework of the day is currently Geb, which builds on top of another functional framework in WebDriver. Geb can be used with the test runners JUnit, TestNG, or Spock. Spock, like Geb is the tool dejour and they are commonly used together. The best thing about Spock tests is that they are easy to read.
New Dependencies in your BuildConfig
To run your functional tests you need to include a number of libraries and plugins in your BuildConfig.groovy. Here is what you typica…