#RestfulApi纏め
##はじめに
RestfulApiの纏めです。
##1.URL
叩いたapiの実行後に叩くapiの完全なリンクをlocation headerで指定しよう。
例：Location: http://hoge.com/api/v1/hoge
##2.レスポンス
エンティティボディはこんな感じにしよう！(異論は認める)
- 正常例 ステータスコード：200、201など適当に
{
"data" : "サンプルデータ",
"message" : "Success make a article"
}
- バリデーションに引っかかった ステータスコード：422
{
"message" : "Validation failed",
"errors" : {
"identify" : [
"The identify is invalid format",
"The identify is too long",
],
"password" : [
"The password is required",
],
}
}
- バリデーション通ったけど失敗 ステータスコード：400
{
"message" : "Failure login",
}
##3.柔軟性
httpパラメータで取得するパラメーターの制限、絞り込み、並び順を指定可能にしよう。カンマ区切りで複数条件可能！
-
fields: 取得したいパラメーター -
getNumber: ページ数 -
pageSize: 1ページの件数 -
sort: 並び替え -
q: 文字列の部分検索
例：/companies/:companyId?fields=data&q=サンプル&sort=id,name
注釈：頻繁に使用する条件はそのurlを用意しておくと、気落ちよく使えるね！
##4.フォーマット
- リクエスト、レスポンスの形式はJSONを使おう
- フィールド名はキャメルケースを使おう
- urlは-区切り
例：/restful-api/
##5.HTTPメソッドを適切に
できるだけこのCRUD表現で対応したい
-
GET: 取得 -
POST: 新規作成 -
PUT: 更新 -
DELETE: 削除
##主要なstatus code
- 200 : OK : 成功
- 201 : Created : 新規作成成功
- 204 : No Content : 成功したが、結果何も返すものがない場合
- 400 : Bad Request : 失敗
- 401 : Unauthorized : 認証が必要
- 402 : Payment Required : 支払いが必要
- 403 : Forbidden : アクセス権がない場合や、ホストがアクセス禁止処分を受けた場合
- 404 : Not Found : 指定したURLに対してリソースが存在しなかった場合
- 422 : Unprocessable Entity : バリデーションに引っかかるエンティティを送った場合
- 500 : Internal Server Error :サーバ内で予期しないエラーが発生した場合や、正常稼働時には発生してはいけない状態を検知した場合
##認証
- 認可はOAuth2を使用する
- OAuth2は認可プロトコルであり、認証プロトコルではない
- OAuth2は脆弱性があるので、セキュリティ対策をとること
##最後に
利用者が叩きやすいApi作成を目指そう！
##参考記事
* WebAPIでエラーをどう表現すべき？15のサービスを調査してみた * HTTP1.1のLocationヘッダは、絶対URLでないとRFC違反