（この記事は、2022/10/01に行われた「気ままに勉強会 #34」で使用したスライドを元にしています）
注意事項
- この記事は、実用性を目指しておりません。何かを解決できる話ではありません。
- この記事は、私が付け焼き刃で仕入れた知識を披露しているだけで、多くの誤りや、個人の見解が含まれていると思われます。
- この記事の内容を鵜呑みにしないでください。
APIはいろいろなものをつなぐ
- APIとは Application Programming Interface
- 「ソフトウエア」のための「インターフェイス」
- 以下のもので構成されています。
- 「仕様」(Specification)
- 「インターフェイス」(Interface)
Web APIはHTTP(HTTPS)を使う
- Web APIとはHTTP(HTTPS)プロトコルを使って 「リモート」 でソフトウエア／サービスを操作するためのインターフェース
- 設備投資は比較的安いコスト、あるいは追加投資無しで実装できます
- HTTP(HTTPS)は既存の技術なので学習コストを低くできます
- その自由さのために統一されたインターフェース、すなわち標準化が求められました。
REST APIとは
REST原則にのっとったAPIは 「RESTful API」 と呼ばれます
-
Addressability （アドレス可能性）
- Uniform Resource Identifier (URI) を使用して、リクエストはリソースを特定します
-
Uniform Interface （統一インターフェース）
- 情報への操作(取得、作成、更新、削除)は、HTTPメソッド(GET、POST、PUT、DELETE)を利用します
-
Client-Server/Stateless （ステートレス性）
- 個々のリクエストは独立しており、リクエストがどのような順番で行われても、同一リクエストは同じ結果を返します。
-
Connectability （接続性）
- アプリケーションと状態遷移の「ハイパーリンク」を動的に作成し送信することで、より多くの情報を情報を取得します
RESTful は原則であり、実装ではないので、開発者の解釈によるところがあります。
雑に説明するのに 「データ形式をXMLやJSONにしておけば大体REST」 などと言われることもありますが、以下の様なことを気にかけておくのが重要です。
- GET, POST, PUT, DELTEの使い分けを考えておく
- URLは、わかりやすいものにしておく
- ハイパーリンクを使うと便利なこともある
- ステートレスのほうが作りやすい、分かりやすいから「ステートレス」にしておく
RESTful APIを記述する言語
- WSDL2.0とWADL → 可読性が低く、あまり採用されていない
- Google Cloud Endpoints
- Open Data Protocol (OData)
- OpenAPI Specification (OAS)
- RESTful Service Description Language (RSDL)
- RESTful API Modeling Language (RAML)
- Apache Avro
OpenAPI 仕様（OpenAPI specificatgion: OAS)とは
歴史
- Tony Tamによって2011年にSwagger APIプロジェクトが開始。
- 2015年、SmartBear SoftwareがSwaggerを買収。
- 2015年、SmartBearは、Google, IBM, Microsoftなどの企業とOpenAPI Initiativeを創設。
- 2016年1月1日、Swagger仕様はOpenAPI仕様(OpenAPI Specification OAS)に改名。
- Swagger 2.0 → OAS 2.0
- 2017年7月、OpenAPI Initiativeは、OAS 3.0.0をリリース
- 2021年2月、OAS 3.1.0をリリース
OASの特徴
- プログラミング言語に依存しない
- クライアントはサーバの実装を知らなくても、サービスを使用できる
- ドキュメント、クライアントライブラリ、ソースコードの同期が保たれる
OASの基本構造
OASファイルはJSONかYAML形式で記述されます。
- Info
- title, version, descriptionなどのメタデータ
- Paths
- APIのパスと仕様を定義する
- Operation, Parameter, Schema
- Server
- サーバーのURLなどを記載できる
- Components, Reference
- リクエスト／レスポンスのセットを定義し、参照する
※ 参照 > "OpenAPI Specification入門", Akinari Tsugo, 2020-05-08, https://garafu.blogspot.com/2020/05/how-to-use-oas.html
YAMLとは
YAMLとは「YAML Ain't Markup Language（YAMLはマークアップ言語ではない）」
- YAMLはカッコではなくインデントでまとまりを表す。
- JSONとYAMLとの交互の変換は比較的カンタン
※ 参照 > "YamlとJsonの比較", TAKIGAWA MEMO, 2020-01-26, https://www.takigawa-memo.com/compare-yaml-json/
OASを書く
代表的なツールは
- Swagger Editor (https://editor.swagger.io/)
- Stoplight Studio (https://stoplight.io/studio)
- Power Automate カスタムコネクタ (https://make.powerautomate.com/)
Swagger Editor
Stoplight Studio
Power Automate
OpenAPI 3 でのカスタム コネクタのサポート
Power Automateのカスタムコネクタで自動で作成されるのはSwagger 2.0 (OAS 2.0)ですが、Swagger エディッタで OAS 3.0.n の記述ができるようになりました。
OASからAzure Functionへの実装
Azure Functions VS Code 拡張機能またはコマンド ラインを使ってOASをインポートすることで、Azure Functionアプリケーションを生成できます。生成後、必要に応じてC#、Python、TypeScript、Javaでビジネスロジックを追加します。
まとめ
