REST API フレームワーク Connexion のススメとその作例

Python の Connexion というフレームワークとそのサンプルアプリケーションを書いたのでその紹介です。

Connexion は「API (spec) First」を謳うフレームワークです。

「API First」とは、 ご存じ The Twelve-Factor App の追補として 2016 年に Pivotal 社が提唱したガイドライン Beyond the Twelve-Factor App の中のひとつです。

簡単にいうと、コードを書き始める前にまずAPIの仕様を定める。たとえば昨今のマルチデバイス対応のような複数チームで開発を進めるような現場で、お互いこのAPI仕様を拠り所とすることで、他方の開発プロセスに干渉することなく、円滑に開発を進めることができる、というものです。 （たぶん）

Connexion はこの API First を実践するのを助けてくれるプロダクトで、OpenAPI （過去に Swagger spec と呼ばれていたものです）で記述した仕様を軸として次のことが実現できます。

  • API 利用者向けのドキュメントを生成できる
  • 仕様に記述した入力パラメータの validation ルール（必須パラメータのあり/なしとか、正規表現で記述した値の形式チェックとか）を自動で実施してくれるので、適用コードを一切書く必要がない

現職で API サーバーを 3 つ実装して、今は Connexion で 4 つめを実装しているのですが、ドキュメントと実装の乖離は頭の痛い問題でした。具体的にいうと、値の形式チェックのルールをちょっと変えたんだけどドキュメントに反映しわすれていたとか、初期に書いたドキュメントの一部が実装から漏れていたとか、みなさんも容易に想像できるんじゃないでしょうか。

また、エンドポイントの情報（HTTPのメソッドとパス）をドキュメントと controller を呼ぶ router の両方に書かないといけないのが常々無駄だと思っていたのですが、Connexion が仕様を読んで所定の controller のメソッドを呼んでくれるので router を記述する必要がなくなったのもよい点の1つです。

Connexion を使うことでこういった問題から解放されたので本当に助かっています。

ほかにも API の動作をちょっと試したりデモするのに便利な Web UI のダッシュボードがついていたり、OAuth 2 のトークンベースの認証に対応していたりといろいろと特徴があるので詳しくは Connexion のサイトをみてみてください。

そんなこんなでここしばらく Connexion の試し書きをしていました。

などのサンプル実装を大いに参考にさせてもらったのですが、もうちょっと実践的な作例を書いてみました。

  • データストアは RDBMS で、 SQLAlchemy ORM の declarative mapping を使用
  • Connexion （の内部の Flask ）との連携は Flask-Alchemy を使用
  • ORM のシリアライズ（dict化）には sqlathanor を使用
  • サンプルとして 2 つのテーブル（リソース）を定義して、one-to-many のリレーション
  • 検索条件の処理は、所定の SQL っぽい記法（JSON）でリクエストをすると、いい感じに SQLAlchemy の query オブジェクトを返してくれる簡易 query builder を書いた
  • pytest と WebTest を使ってテストも用意した

まだまだ Python は B- ぐらいウデマエの上に SQLAlchemy なども使ったことがなかったので、「こう書いたほうがいいでし！」とかあったらぜひ プルリ お待ちしています！