UUUM攻殻機動隊(エンジニアブログ)

UUUMのエンジニアによる技術ブログです

API BluePrintで定義ファーストなAPI開発

こんにちは、エンジニアのナカハシです。

隠れドラゴンズファンなので久々に観戦に行ったら、10点差を追いつかれてサヨナラ負けしました。世知辛いにもほどがありますね!!!!!!!(怒)(泣)


サーバーサイドとフロント/アプリを別チームで開発するといったケースでは、互いのシステムのインターフェイスはAPIになります。なので、API定義の共有は重要です。

APIのドキュメンテーションやチーム開発を支援する、API BluePrintについて、色々試してみました。

なにそれ?

API BluePrint は、API用に特化したドキュメンテーションのための言語です。以下のような特徴があります。

  • 主にMarkdownで書く → 誰でも読み書きできる
  • きれいなドキュメント出力
  • モックサーバーも作れる

とにかく書く

まずはAPIの概要を書きます。公式のExample が充実しているので見ながら書くといいでしょう。雰囲気はこのような感じです。

FORMAT: 1A
HOST: https//api.example.com

# /message
リソース名書く。

## GET
GETの場合の機能を書く。

+ Response 200 (text/plain)

    + Headers

            X-My-Message-Header: 42

    + Body

            { "message": "Hello World!" }

最初の FORMAT: 1A は、API BluePrintのバージョンです。

+ Response 200 (text/plain) 以降はこのAPIの内容を記述している部分です。ここだけは記法が独自になりますが、シンプルな仕様なのですぐに覚えられるでしょう。

細かい話ですが、インデントで使うスペース数は固定で4つです。そして + Headers+ Body の次のインデントは一見2段目に見えるのですが、3段目(12スペース)にする必要があります(さもないと、後述の出力ツールで警告出ます)。この辺は若干罠ですが、とにかく公式通りに書きましょう。

HTMLに出力してみる

API BluePrint自体はただの記述言語なので、出力するためのツールが必要です。今回は割とよく使われている Aglio を試してみましょう。npmモジュールです。

先ほど「とにかく書いた」APIを出力してみましょう。

$ vim index.md  # とにかく書く
$ npm install aglio
$ node_modules/.bin/aglio --theme-variables slate -i index.md -o ./index.html

これだけで、カレントディレクトリに美しいドキュメントが出力されてます!

f:id:k_nakahashi:20170727182822p:plain

GitHub Pagesに出力してみる

GitHubには、簡単に静的ページを公開できる GitHub Pages という機能があります。せっかくHTMLに出力したので、Github Pagesを公開してみましょう。

GitHub PagesでHTMLを公開するのは簡単で、gh-pagesというブランチを切り、そこにindex.htmlを格納すればいいだけです。

API BluePrintで書いたMarkdownファイルですが、もちろんGitなどの構成管理ツールで管理すべきです。そしてこれをソースとしてAglioでHTMLを出力して閲覧するという使い方を考えると、HTMLはコンパイル結果のバイナリみたいなもので、構成管理ツールでの管理対象ではなくてもいいはず。

以上により、API BluePrintファイルをapi-docブランチで管理し、そこで得られるHTMLをgh-pagesにpushするという方法を考えました。API BluePrint→HTMLへの変換とgh-pagesへのpushは、CircleCIで自動化します。api-docブランチへのpushをトリガに動かせるといい感じです。

上記のような circle.yml のサンプル を書いてみました。

出力結果は こちら で見れます。

いい感じにできたとは思うのですが、GitHub Pagesは(privateリポジトリであっても)無制限に公開されちゃいます。用途的にOKならこの手を試してみましょう。

ドキュメントを動かす

非常に良いのが、ドキュメントがそのままモックサーバーになってくれることです。

さきほどとにかく書いた手順に続けて、モックサーバーを動かしてみましょう。モックサーバーはいくつか選べますが、手元で動かせたのは drakov でした。

$ vim index.md  # とにかく書く
$ npm install drakov
$ node_modules/.bin/drakov -f index.md -p 8081 --watch
[INFO] No configuration files found
[INFO] Loading configuration from CLI
   DRAKOV STARTED   
[LOG] Setup Route: GET /message 
   Drakov 1.0.4      Listening on port 8081
 FILE SPY   ACTIVE 

何やらうごめいています。curlで突っついてみましょう。

$ curl http://localhost:8081/message
{ "message": "Hello World!" }

ドキュメントに書いた内容が返ってきました。スゴい!

競合とワークフロー

API Blueprint創始者が語るAPIの進歩 という記事がおもしろかったので、少し引用します。

Swagger v2.0やRAML v0.8と比較した時,API Blueprintの最大の強みは何でしょう?

Jakub Nestril: API Blueprintは最もヒューマンフレンドリなフォーマットです。開発者やプロダクトマネージャ,ドキュメントライタ,アーキテクトといった人たちに広く利用されています。最大の強みは,このすべてを同じテーブルで提供できることです。

YAMLなどのフォーマットで書くと、パースエラーなど色々面倒なことがありますからね。

API Blueprintを使用する場合,基本的な開発ワークフローはどのようなものになりますか?

JN: ワークフローでもっとも画期的なのは,APIバックエンドチームとAPI利用チームが,APIの両側で並行して共同設計,共同開発ができることです。Apiaryでまず最初に,モックサーバを構築した理由がここにあります。

「共同設計」「共同開発」のために、書きやすいMarkdownライクなフォーマットとすぐ動くモックサーバーを採用しているということがわかります。

アジャイルスタイルのいまどきの開発に、とてもマッチしているのではないでしょうか?

まとめ

10点差あっても、勝ちパターンの投手を出していく慎重な姿勢が大事です。