Tuesday, October 29, 2013

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.


Currently, the best resource for example snippets of the API syntax is in a Github repository (of course). It is worth pointing out that, as Github will format these sample documents according to the markdown standard, to get any kind of value from them, you need to view them in raw format. While the examples are useful, to really get to grips with writing the the API documentation you will need to read the language specification. There is also a nice third-party example in the form of unofficial documentation of the Tesla Model S api. You can also checkout the apiary tutorial.





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.


Check out the Dredd Github repository for more info.


Summary


  • I've been playing with Apiary and API Blueprint for about a week now, and I'm already hooked.
  • A standard syntax and document structure helps to design better APIs. 
  • The collaboration aspect means there is no excuse for not getting feedback early. 
  • The lack of vendor lock-in is a real comfort. Just like with Github, I know that if ever I am unhappy with the service, I can always move my documentation in house, or to an alternative service.
  • Apiary also supports multi-markdown which covers some of the feature gaps in plain Markdown (such as tables).
  • I'm looking forward to taking Dredd for a spin, but I'm not in a rush to dive into the code just yet.



2 comments:

  1. đồng tâm
    game mu
    cho thuê nhà trọ
    cho thuê phòng trọ
    nhac san cuc manh
    số điện thoại tư vấn pháp luật miễn phí
    văn phòng luật
    tổng đài tư vấn pháp luật
    dịch vụ thành lập công ty trọn gói
    lý thuyết trò chơi
    đức phật và nàng
    hồ sơ mật dinh độc lập
    đừng hoang tưởng về biển lớn
    chiến thắng trò chơi cuộc sống
    lượng tử
    ngồi khóc trên cây
    truy tìm ký ức
    mặt dày tâm đen
    thế giới như tôi thấy
    “Thực ra ta đã sớm nhìn ra ngươi không phải là cá trong ao tù, Giang Nam tuy tốt nhưng vẫn không phải là nơi thích hợp với nhân tài.” Vương Đức Vọng thật lòng nói: “Phong nhi, kinh đô là nơi ngọa hổ tàng long, ngươi đi lần này nhất định phải làm việc một cách cẩn trọng, khi làm thì phải để ý một chút. Bất quá ngươi đã có quý nhân tương trợ, vấn đề này cũng không lớn lắm.”
    “Quý nhân?” Lưu Phong cười nói: “Vương đại nhân nói đùa, ta làm gì có quý nhân tương trợ.” Trước kia lúc Trương Thiên Sư còn sống thì cũng tính là có. Bây giờ lão nhân gia đã không còn thì làm gì còn quý nhân nào nữa. Phùng Nguyệt và Bạch Thọ mặc dù đồng tâm với mình, tuy nhiên tiếng nói của bọn họ trước mặt bệ hạ cũng chỉ có tí phân lượng nào thôi.
    Vương Đức Vọng ha ha cười nói: “Kim Vận bá tước và quan hệ của ngươi hẳn là rất tốt còn gì nữa.”
    Lưu Phong hơi run một chút, thầm nghĩ hóa ra người mà Vương Đức Vọng cho là quý nhân của mình là nàng à. Tại một nơi như kinh đô thì một nữ bá tước tựa hồ cũng không tính làm gì.
    Vương Đức Vọng vỗ bả vai hắn, thấp giọng nói: “Đừng xem Kim Vận phu nhân chỉ là một bá tước, cũng đừng xem như hạng nữ lưu thông thường, năng lực của nàng rất lớn. Vĩnh viễn không nên xem thường nữ nhân, nhất là đàn bà góa chồng. Lần này nếu bệ hạ triệu ngươi vào kinh thì ngươi nhất định phải dựa vào ưu thế của Kim Vận phu nhân để mà thiết lập mạng lưới quan hệ của mình.
    Lưu Phong thấp giọng hỏi: “Kim Vận phu nhân đích thực là một người đàn bà có cá tính độc lập, mặc dù nàng và ta có chút giao tình nhưng vị tất nàng đã đem hết sức giúp ta.”
    “Hắc hắc” Vương Đức Vọng đột nhiên nhìn Lưu Phong cười một cách mập mờ: “Đừng tưởng rằng ta không biết, giao tình giữa hai ngươi tuyệt đối không

    ReplyDelete