APIとは #API

データ通信形式

主に、XMLとJSONがあります。
XMLは、最近見ないがYahoo!などでレスポンス形式として使われている。
JSONに比べ、記述する項目が多く、新しくAPIを作るのであれば推奨されない。

最近では、JSONが一般的。
JSONもフォーマットとして構造化され、記述量が少ないので、データ通信形式としては非常に扱いやすく、可読性も高い。

「なぜAPI設計を作ろうとしているのか」という目的を明確化すること。

外部APIであれば、「どのデータを公開するか」を選定し、
「ユーザーに何を取得させたいのか、または編集させたいのか」を決めること。

内部APIであっても、「どのサービスに使わせる予定か」「どうしてDBアクセスではなく、APIにするか」という理由を明確化すること。

APIを介するということは、DB操作と比較してオーバーヘッドがあることを忘れてはいけない。

APIを作る理由を決めることは、どのデータをAPIとして触れるかを決めることです。

APIの設計という意味では、HTTPリクエストにおける「エンドポイントの設計」と「レスポンスの設計」がある。

エンドポイント設計する上での注意点。

APIは一般的にセッション管理のようなものはなく、1リクエスト1レスポンスで完結するため、状態を持ちません(ステートレス)。
そのため、一つのリクエストで必要な情報を受け取るRESTfulの考え方にはマッチしているのです。

HTTPリクエストを送信する方法として大きく2つ。
1) JSON
2) フォーム

フォーム形式が一番基本的です。
フォームでのPOST送信の場合、文字データだけではなく、画像や動画などのバイナリデータも送ることができます。

JSON形式
こちらは構造化したJSONデータなので送る際に可読性が上がるというメリットがある。

代表的なHTTPメソッド
HTTPリクエストを送る際、HTTPメソッドで送る必要があります。

GET
リソースを取得するメソッド。
GETメソッドで情報を登録/変更するのは、基本的に禁止です。
情報を取得するだけのメソッドである。

POST
リソース情報を作成・登録する場合に用います。
すでにあるリソースを変更する場合は、PUTやPATCHを利用。

PUT
すでにある何らかのリソースを変更する処理。
URLを以下のようにして特定することが多い。
http://api.example.com/users/:userId

DELETE
削除処理を行うのがリソースです。
PUTと同じようにURLにリソースIDを含めるのが一般的です。

PATCH
変更処理を行うメソッド。
PATCHとPUTの違いは、PUTが指定したリソースの要素を全て入れ替えるのに対し、
PATCHは一部だけ入れ替えるイメージです。
ただPATCHに関しては、対応しないフレームワークもあるので採用は慎重に。

POSTやPUTなどの変更系のAPIにおいては、レスポンスにリクエストを返却してあげると
例えばtwitterなどレスポンスにリクエストを含めています。

エラー

200系：正常系
300系：リダイレクト系
400系：ユーザーの入力がおかしい場合
500系：サーバー内にて何かエラーが起きている

エラーレスポンスに対して、どのようにエラーメッセージを返せば良いか。
返し方は下記の2通り。

実際にAPIを利用している際に、「どうやってエラーが返ってきているのか」を確認する際に、ヘッダを確認するよりもボディの内容を確認する方が楽なので、ボディに入れて返してあげるのがユーザーフレンドリ。

ヘッダ
ヘッダに情報を入れるケースは、多いと思います。
例えば、認証のための情報を例に挙げると「X-Auth」「X-Token」などが使われます。
自分で定義したものに関しては、「X-」をつけるのが一般的です。