🔰

Web API開発をはじめるまえに

2024/06/11に公開

Java

API開発をはじめるプログラマーの方向けに、API開発の全体像をまとめました。

Web APIとは？

API（Application Programming Interface）とは、アプリケーション間での情報や機能のやり取りを可能にする窓口を意味します。
Web APIでは、Webサービスで提供している機能やデータを外からプログラムが読み取りやすい形で利用できるよう定めた規約や手順が定義されています。
Web APIにはいくつも種類がありますが、代表的に使用されているREST APIについて触れていきます。

Web APIの代表的な規約：REST API / RESTful API とは？

REST（representational state transfer）は、クライアントとサーバーの間でデータをやり取りするための６つの原則（必須５、任意１）です。
REST自体は「設計の考え方」であって具体的な実装ではありません。
RESTの原則に従って開発されるAPIをREST APIまたはRESTful APIと呼び、HTTP リクエストを活用してデータにアクセスします。

RESTの6つの原則は、以下になります。

クライアント/サーバーアーキテクチャ：REST APIは、クライアント（情報を要求する側）とサーバー（情報を所有する側）を分離する。クライアントは、サーバーがどのようにデータを保存し、取り出すかを気にする必要はない。
統一されたインターフェース：クライアントがソフトウェア・アプリケーションであろうと、ブラウザであろうと、モバイルアプリであろうと、まったく別のものであろうと、同じように REST API にアクセスして使用することができる。
ステートレス：サーバーはクライアントの状態（ステート）を覚えておく必要はない。また、クライアントのリクエストはすべて「ステートレス」でないといけないので、各リクエストにはクライアントの認証情報などの必要な情報がすべて含まれていないといけない。
キャッシュ能力：REST サーバーはデータをキャッシュし、将来の他のリクエストに再利用することができる。
階層システム：REST API には、クライアントとサーバーの間に複数の仲介層がある場合があるが、クライアントはその実装の詳細を知る必要はない。
コード・オン・デマンド（任意）：クライアントは、JavaアプレットやJavaScript スクリプトなど、実行時に追加機能にアクセスするためのコードをダウンロードすることができる。

引用：REST API ツール７選

この中でもAPI開発者として留意しておきたいのは、統一されたインターフェースという原則です。
簡単に言うと、APIにアクセスさせるための接続先URLのルールは統一しましょうということです。

URIの設計方法は下記のようなルールが推奨されています。

短く入力しやすい
人間が読んで理解できる
大文字小文字が混在していない
改造しやすい
サーバ側のアーキテクチャが反映されていない
ルールが統一されている

引用： Web API: The Good Partsを読んだまとめ

設計ルールに従った URI は例えば次のようになります。

目的	URI	メソッド
注文の一覧取得	https://azunyan.com/orders/	GET
注文の新規登録	https://azunyan.com/orders/	POST
特定の顧客の注文の取得	https://azunyan.com/orders/{顧客ID}	GET

統一的なルールのもと設計されていないとAPIの利用者がAPIを活用しにくくなってしまう為、統一感のあるURIを設計できるよう開発者間で連携をとりましょう。

次にREST 原則に則った実装はどう行っていくのか？を見ていきます。

Web APIの設計を行う：OpenAPIとは？

OpenAPI仕様とは、APIの仕様を記述するための標準規格です。
最近では多くのWeb APIがOpenAPI形式で公開されており、RESTful APIの仕様を記述するためのフォーマットとして広く利用されています。

OpenAPIの主な特徴を3つご紹介します。

1. APIを決まったフォーマットで規定できる

YAMLやJSON形式でAPIのエンドポイント、メソッド、パラメータ、スキーマなどを定義します。

openapi: 　　　  # 必須： Open APIのバージョンを指定
info:            # 必須： APIのタイトル、バージョン等の基本情報を定義
　...
servers:         # API サーバのエンドポイントのURLを指定
　...
tags:            # APIを整理するために利用するタグを定義
　...
paths:           # 必須： メインとなる部分で、APIとして利用可能なパスおよびメソッドを定義
　...　　　　　　# 下記のcomponentsを呼び出せる。
security: 　　　 # API全体にかけるセキュリティ要件
　...　　　　　　# Components内にセキュリティ要件を定義し、pathsより呼び出すことも可能　
components:      # APIの中で利用する様々なオブジェクトをコンポーネント化して再利用可能にする
　...

必須項目の openapi: / info: / paths: のみ記述しておけば、APIが作れます。
参考：OpenAPI (Swagger) 超入門

2. ドキュメントを生成できる

1.で作成したAPIスキーマを元にドキュメント生成してくれます。
APIドキュメントは、APIの使用方法や機能に関する情報を提供する文書です。APIを利用したい人がAPIを正しく理解するために必要なものです。

下記は、「Hello World！」を返すOpenAPIの仕様ファイルからOpenAPI Generatorでドキュメントを生成したものです。

3. API仕様書からコードを一部自動生成できる、またはコードからAPI仕様書を自動生成できる

APIのリクエストやレスポンスのインターフェースを設計をした後は、OpenAPI generatorを使用すると様々な開発言語でコードの一部自動生成が可能です。
API定義から生成したので当たり前ですが、生成できるサーバサイドのコードはロジックが記述されていません。そのため、実際にAPIサーバとして利用するためにはこのあとにロジックを書く必要があります。

開発アプローチとしては下記の２つの選択肢があります。

API仕様書からコードを生成する･･･「スキーマ駆動開発」または「スキーマファースト」と呼ばれます
コードからAPI仕様書を生成する･･･「コードファースト」と呼ばれます

どちらのアプローチをとるかは、両者ともメリット・デメリットがありますので下記をご参考ください。

開発アプローチ：APIファースト VS. コードファースト

下記は、スキーマ駆動開発の手法で、「Hello World！」を返すOpenAPIの仕様ファイルからOpenAPI Generator でコードを生成したものです。開発言語はJavaです。

Web APIのテストをしよう

APIが正確に仕様通りに動作するかを検証する必要があります。
これには、リクエストとレスポンスの形式、データ型、エラーコード、セキュリティ要件など、API仕様のすべての側面が含まれます。
詳細については下記をご参考ください。

まとめ

APIを開発するための流れを見てきました。

APIの設計・ドキュメント作成:APIの仕様を記述し、開発者向けのドキュメントを作成する。
APIの設計に合わせてバックエンドの実装をする。
APIのテスト：APIが正確に動作することを保証するために、APIをテストする。

最後になりますが、これらのAPI開発を効率的に行い、またAPIを公開・管理できるAPIプラットフォームもありますので、ご参考ください。

以上、えみり〜でした|ωΦ)ฅ
良い開発者LIFEを。。☆

参考

APIとは？どんな流れで学べばいいのか？どう開発していけばいいの？というイメージを掴むためにまずおすすめしたい4つ。

Restful APIとは

スキーマファースト　VS　コードファースト

スキーマファースト

コードファースト

APIプラットフォーム