Partsを読んで改めて気づいたことやメモしておきたいことなどをまとめました。APIは基本的にHTTPがエンベロープの役割を果たしているから使う必要なしエラーの詳細をクライアントに返すときはレスポンスボディに格納することもAPIをバージョンで管理するバージョン番号の付け方メディアタイプの指定Content-Typeで指定する必要性エンベロープを使うべきかエンベロープとは日本語で言うと「封筒」を意味します。APIデータ構造の文脈で言えば、以下のように全てのデータを同じ構造でくるむことを言います。"1",...}}上記の例では、headerとresponseという2つのデータを保つ構造をしており、headerにはステータスなどのメタデータを入れ、responseには実際のデータが格納されています。エンベロープは、こうしたメタデータも含みデータをくるむような構造をしています。APIは基本的にHTTPがエンベロープの役割を果たしているから使う必要なしメタデータなどをレスポンスに含めることで、クライアントサイドが扱いやすくなると言うメリットはあるものの、このエンベロープは冗長な表現であるため、基本的には使うべきではありません。HTTPにはヘッダの概念があり、そこにステータスコードなどのメタデータを入れて返すことができ、わざわざレスポンスにまで含めると冗長化するからです。エラーの場合でもステータスコードが200番になっていたりすると、処理が成功したのか失敗したのか判別できなくなります。エラーの詳細をクライアントに返すときはレスポンスボディに格納することもエラーの詳細を返す方法は大きく2つあり、1つ目はHTTPのレスポンスヘッドに入れて返す方法、2つ目はレスポンスボディにいれて返す方法があります。1つ目のレスポンスヘッダに入れる方法は、以下のように独自に定義したヘッダ項目を用意して格納します。http://api.example.com/v1/auth2つ目のレスポンスボディに入れる方法は、以下のようにJSONのレスポンスボディとして、エラーのデータ構造を用意して格納します。“http://api.example.com/v1/auth”}}先程のエンベロープの話からすると、エラー情報はヘッダに入れた方が良い気がしますが、実際に公開されている多くのAPIがボディにエラーメッセージを格納する方法を採用しています。複数のエラーが同時に発生した場合など、ボディに配列を用意してそこにエラーを格納することができるため、このようなエラーの場合などは、ヘッダに独自の項目を用意するより、ボディで対応した方が良い場合もあります。APIをバージョンで管理するバージョン番号の付け方バージョニングのルールとして広く知られている手法にセマンティックバージョニングがあります。セマンティックバージョニングでは、バージョンは基本的には”1.2.3”のように3つの数値をドットで繋いだものになっています。それぞれ数値は先頭からメジャー、マイナー、パッチと呼ばれています。メジャー:後方互換性のない変更が行われた場合に増えるマイナー:後方互換性のある機能変更、あるいは特定の機能が今後廃止されることが決まった場合に増えるパッチ:ソフトウェアのAPIに変更がないバグ修正などを行った場合に増えるAPIの場合は、複数のAPIバージョンのメンテナンスやユーザからの利便性の観点からも、頻繁にバージョンを上げるべきではないため、メジャーバージョンで表すのが適切といえます。以下のようなURIのパスにバージョンを入れ、メジャーバージョンで管理するのが一般的です。1https://api.example.com/v1メディアタイプの指定HTTPのリクエスト、レスポンスでは送信するデータ本体の形式を表すためにメディアタイプを指定する必要があります。メディアタイプはデータ形式のことで、レスポンスデータがJSONなのかHTMLなのか、画像なのかなどを示しています。リクエストの場合は、クライアントがどのようなメディアタイプを理解できるか指定することができます。レスポンスの場合は、以下のようにヘッダのContent-Typeを利用してメディアタイプを指定します。データを読み出せない場合があるクライアントの多くは、まずはContent-Typeの値を使ってデータ形式を判断しており、その指定を間違えると正しくデータを読み出すことができない場合があります。AFNetworkingというライブラリでは、application/json、text/json、text/javascriptのメディアタイプのみ受け入れており、それ以外はエラーになります。このようにメディアタイプが厳格である場合には、Content-Typeを正確に指定しないとエラーに悩まされることになります。セキュリティ上の問題を引き起こす実際のレスポンスデータと異なるメディアタイプをContent-Typeすることで、セキュリティ上の問題を引き起こすこともあります。JSONファイルを誤ってtext/htmlで配信してしまった場合、データ通信を実現するXMLHttpRequestでそのJOSNファイルにアクセスしても問題なくデータを取得、解析できます。このJSONファイルのURIを直接叩いてアクセスした場合、ブラウザはContent-Typeを元にデータ形式を認識するため、HTMLとして表示されます。そのため、以下のようなJavaScriptが埋め込まれていた場合、実行されてしまうのです。}Content-Typeにapplication/jsonを指定していれば、ほとんどのブラウザの場合実行されることはありません。メディアタイプを正しく指定してもまだ問題は発生する可能性はありますが、正確にデータのやり取りをする上でもContent-Typeを指定する必要性があります。コメントをキャンセルメールアドレスが公開されることはありません。コメントデータの処理方法の詳細はこちらをご覧ください。