APIの設計や実装の課題とその解決策をご紹介します。APIの設計について解説しました。Gatewayにインポートする方法について説明します。GatewayはAWSの提供するマネージド・サービスです。API公開に一般的に必要だと考えられている機能を提供しています。GatewayをHTTPプロキシとして使います。Gatewayのような独立したサービスや製品が必要なわけではありません。公開するAPIがひとつだけであれば、認証機能をAPIの機能の一部として実装することもあります。複数のAPIを公開する場合に、個々のAPIに依存しない共通の機能をAPIゲートウェイが提供し、クライアントはAPIゲートウェイを経由し実際のAPIにアクセスするというアーキテクチャは一般的です。Response)の定義です。Gatewayの設定画面です。Responseを設定するようになっているのがわかるでしょう。APIのインターフェースを記述するための仕様です。元々は、Swagger仕様を使ったコード生成やインタラクティブなドキュメント用のツールなどと一緒にWordnik社によって開発されました。Initiativeに寄贈されました。2Swagger仕様は、JSON、あるいはYAML形式をサポートしています。以下の例は、この記事で使うAPIをYAML形式で記述したものです。RESTのAPIを使ったことのある開発者であれば、ざっと目を通すだけで簡単に理解できるはずです。リソースのURLのベースとなるのはhost、schemes、basePathです。paths以下はリソース固有のパスとサポートしているHTTPメソッドとURLのパラメータ、レスポンスのボディに含まれるデータのモデルを定義しています。’#/definitions/Users'は、レスポンスのHTTPステータスが200の場合、このファイルの後半部分に定義されているUsersスキーマのデータを返すことを定義しています。UIはインタラクティブなAPIのドキュメントを生成するツールです。Swagger仕様を読み込みドキュメントを表示するだけでなく、実際にAPIを呼び出し、その結果を見ることができます。aws-apigateway-importerは、Amazonの開発しているOSSのコマンドラインツールです。Gatewayにインポートすることができます。この記事ではSwaggerを使ってインポートする方法を説明します。Gatewayの設定はAWSマネジメントコンソールからもおこなうことができます。RESTリソースや環境が増えてくると、設定内容や手順をドキュメント化し、人手で設定するのは苦痛です。aws-apigateway-importerのようなツール3を使い、できる限り自動化すべきです。ツールを使うと、設定ファイルをバージョン管理することができるようになるのもメリットのひとつです。aws-apigateway-importerの使いかた概要aws-apigateway-importerはJavaで書かれたコマンドラインツールです。Capitan上で動作を確認しています。ソースコードの中には起動用のシェルスクリプトとバッチファイルが含まれているので、おそらく他のUnix系のOSとWindowsでも動くと思われます。現在のところソースコードのみの提供ですので、ビルド方法を後ほど説明します。ヘルプを表示させるために、–helpオプションを指定して起動用のシェルスクリプトを実行してみましょう。APIaws-apigateway-importerがサポートしているのはAPIのインポートとアップデートの2つの操作で、それぞれ-c、-uオプションに対応しています。それ以外のオプションは必須ではありません。基本形は以下の2つです。Gatewayを操作するためにはAWSのアクセスキーが必要です。ユーザーのアクセスキーの管理」を参照し、アクセスキーを作成してください。SDK/CLIの設定ファイル、インスタンスプロファイルのいずれかの方法で設定することができます。Java」を参照してください。ここでは、環境変数を使います。Gateway用の定義Swagger仕様はベンダーによる拡張をサポートするために「x-」ではじまるフィールドを予約しています。Gateway固有の設定を可能にしています。以下は、この記事で使う設定の一部です。x-amazon-apigateway-integration以外にも、認証定義のためにx-amazon-apigateway-authフィールドを使うことができます。Gatewayの設定はリソースのパスとメソッドの組み合わせに対しておこないます。この例では、/usersというパスとGETメソッドの組み合わせです。Requestに設定された内容です。Parametersのマッピングです。AWS管理コンソールでは2つに分かれていますが、ここではまとめて指定します。キーはintegration.request.{location}.{name}という形式で指定します。locationにはquerystring、path、headerのいずれかを使うことができます。それぞれ、URLのクエリストリング、URLのパス、HTTPヘッダーを意味しています。nameはユニークな任意のパラメータ名です。値の部分はmethod.request.{location}.{name}という形式で指定します。locationとnameはintegrationと同様です。Requestに設定された内容です。Responseのマッピングです。ここでは、フォーマットの変換などをおこなっていないので特別な設定はおこなっていません。ソースコードに含まれているREADME.mdによると、以下のようにレスポンスのパラメータのマッピングやテンプレートの指定ができるようです。},https://github.com/awslabs/aws-apigateway-importer/blob/master/README.md残念ながら、ステージ毎に設定するキャッシュやスロットリングなどの設定はまだサポートされていません。作成するを参照してください。APIのインポートでは、APIをインポートしてみましょう。ここでは、-rオプションを使い東京リージョンにインポートします。getこれでインポートは完了です。今度はAPIを更新してみましょう。APIの更新時には、APIのidが必要です。インポート時のログ、あるいは管理コンソールでAPIを表示している時のURLを見れば、APIのidがわかります。上のインポートの例では、APIのidはl5yjz5pos5です。resourcesaws-apigateway-importerのビルドaws-apigateway-importerはソースコードでのみ提供されているため、使う前にビルドする必要があります。ここでは、ビルド方法について説明します。以下のソフトウェアをインストールしておく必要があります。MavenビルドGitHubからaws-apigateway-importerのリポジトリをクローンして、Mavenでビルドします。------------------------------------------------------------------------正しくビルドできたことを確認するために、ヘルプを表示させてみましょう。import省略これでビルドは完了です。まとめaws-apigateway-importerを使うと、設定をバージョン管理し、人手によるオペレーションを減らすことができます。Gatewayを使う場合には利用を検討すべきでしょう。(2016/08/08:「オージス総研の取り組み」の内容を変更しました)脚注アーキテクチャとしてのAPIゲートウェイに興味のある方は、オブジェクトの広場の記事APIゲートウェイアーキテクチャ」を参照してください。設立に伴いOpenAPI仕様と改名されました。aws-apigateway-importerのドキュメントではまだSwaggerとして参照されています。混乱を避けるためにこの記事では、Swaggerに統一しています。Gateway経由でのAPI公開をサポートしています。Gatewayサポートを実装中です。↩ヘルプの出力が奇妙なのは不具合のようです。クラス図、シーケンス図、ユースケース図——必修ダイア...オージス総研の取り組みAPI公開支援ソリューションお客さまがAPI公開を素早く始められるよう「API構築」と「APIの運用」を包括的に提供します。迅速なAPIの公開、継続的なAPIの改善を実現し、お客さまのAPIによるビジネスのデジタル化を支援します。