Contents

WEB APIのURL設計

そのURLがAPIであることを表す方法は大きく分けて2種類あります。サブドメインに置き http://api.example.com/ とするか、パスに置き http://example.com/api/ とするか、です。

WEB API開発の基本

今回はWeb API開発の入門ということで、簡単なWeb APIを作成してみます。

https://github.com/TinyWebDB/tinywebdb-php

作成するもの

リクエストを送ると、登録してあるユーザーを取得できるWeb APIを作成します。ユーザーの一覧を取得できるだけでなく、IDをパラメータとして送ることで、特定のユーザーを取得できるようにします。

本来であればDBにユーザーデータを持たせ、新規登録・更新・削除などもできるようにしますが、今回は簡略化のために省きます。ユーザーのデータはあらかじめ配列で持たせておくことにします。

言語

Web APIを開発するにあたり、スタンダードとなっている言語は特にありません。
今回は私が普段の開発で使用しており、使用者数も多いPHPを使います。

エンドポイント(URI)

Web APIはURIにリクエストを送ることで、データの取得や操作を行います。
そのため、簡潔で、どのような機能を持つのかが分かりやすいURIを設計することが重要です。
一般的に重要だとされる点は以下のようなことです。

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

今回は以下のように設計します。本来はURIに拡張子を含めるのはよくありませんが(サーバー側のアーキテクチャが反映されているため)、今回は簡略化のため表示したままとしています。

目的	エンドポイント	HTTPメソッド
ユーザーの一覧取得	http://localhost/api/users.php	GET
特定のユーザーの情報の取得	http://localhost/api/users.php?id=X	GET

今回は実装しませんが、ユーザーの新規登録・更新・削除を行う場合は以下のようになるはずです。

目的	エンドポイント	HTTPメソッド
ユーザーの新規登録	http://localhost/api/users.php	POST
ユーザーの情報の更新	http://localhost/api/users.php?id=X	PUT/PATCH
ユーザーの情報の削除	http://localhost/api/users.php?id=X	DELETE

HTTPメソッドについて簡単に説明しておきます。 HTTPメソッドとは、HTTPでのアクセス時に指定するもので、GETやPOSTなどが有名です。 URIとHTTPメソッドの関係は、「操作する対象」と「操作方法」の関係にあります。以下に一覧を示しておきます。

HTTPメソッド名	説明
GET	情報の取得
POST	情報の新規登録
PUT	既存の情報の更新
DELETE	情報の削除
PATCH	情報の一部変更
HEAD	情報のメタ情報の取得

レスポンスデータ

Web APIのURIにリクエストを送ると、その結果(レスポンスデータ)が返ってきます。
Web APIのレスポンスは他の開発者が利用することが前提なので、なるべくプログラム内部で利用しやすい形式にすることが望ましいです。

データフォーマット

まず最初に、レスポンスデータをどのようなデータフォーマットで返すのかを考える必要があります。
現在、Web APIで利用されている主なデータフォーマットは大きく分けて以下の２つです。

JSON
XML

かつてはXMLがよく使用されていましたが、現在はJSON形式で返すのが主流になっています。
今回もレスポンスデータはJSONで返すこととします。

{
    "status": "OK",
    "users": [
        {
            "name": "yamada",
            "age": 20
        },
        {
            "name": "suzuki",
            "age": 25
        },
        {
            "name": "matsuda",
            "age": 30
        }
    ]
}

ステータスコード

レスポンスを返す際には、適切なステータスコードを返します。
ステータスコードとは、「200」や「404」など3桁の数字で表され、HTTPレスポンスヘッダの先頭行に記載されています。
「200 OK」や「404 Not Found」などはブラウザ画面にも表示されるため有名です。

以下にステータスコードの分類を示しておきます。

ステータスコード	意味
100番台	情報
200番台	成功
300番台	リダイレクト
400番台	クライアントサイドに起因するエラー
500番台	サーバーサイドに起因するエラー

エラー表示

Web APIは様々な要因でエラーを返す可能性があります。
エラーを返す際にはステータスコードを付与しますが、それだけでは不十分です。
Web APIを利用している側が、なぜエラーになったのかを具体的に分かるようにしておきます。エラーを返す際にはエラーの詳細について、レスポンスボディに含めて返すのが一般的ですので今回もそのようにします。

{
    "status": "NG",
    "message": "Invalid parameter"
}

セキュリティ

今回は入門の記事ということで実装は行いませんが、Web API開発に置いてセキュリティ対策に気を配ることは重要です。
特に機密情報などを扱っている場合、悪意のある利用者から情報を保護するための対策を行っておかなければ大事故に繋がりかねません。
本格的なWeb APIの開発・公開を考えておられる方は、別途セキュリティについての情報を確認することをおすすめします。

REST APIドキュメント作成ツール

apiary
swagger
iodocs
autodoc
RESTdoclet
carte
mashape

WEB API検証ツール

Postman for Chrome – There are many Chrome apps for making HTTP requests, this one is the best. (Free + Paid)

Make your Web API

Create API