Create API

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で利用されている主なデータフォーマットは大きく分けて以下の2つです。

  • 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)