LoginSignup
49

More than 5 years have passed since last update.

RestfulApiの設計書

Last updated at Posted at 2016-11-07

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作成を目指そう!

参考記事

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
49