b→dash APIの共通仕様とは
b→dash APIの共通仕様とは、全てのb→dash APIを開発・導入・利用する上で共通して適用される注意事項です。本記事では「接続方式」「非機能要件」「リクエスト共通仕様」「ステータスコード共通仕様」「エラー発生時のレスポンス」の5項目について記載しています。
各b→dash APIの共通の仕様に関してまとめていますので、それぞれの記事に記載のない仕様については本記事をご参照ください。
接続方式
貴社の基幹システム/アプリケーションにb→dash APIを開発する際は、下記の接続方式をご参照ください。
| 項目 | 接続方式 |
| 認証方法 | OAuth2/APIキー方式 |
| プロトコル | HTTPS |
| データ形式 | JSON |
非機能要件
全てのb→dash APIは下記の非機能要件を持ちます。
| # | 項目 | 上限の単位 | 非機能要件 |
| 1 | URI長の上限 | 1リクエストあたり | 10KBまで |
| 2 | 全体サイズ上限 | 1リクエストあたり | 3MBまで |
| 3 | レスポンス | 1リクエストあたり | リクエストからレスポンスの間は5秒以内 |
| 4 | 月間リクエスト上限数 | 1アカウントあたり |
10万リクエストまで
※超過した場合でも、エラーになりません |
| 5 | 分間リクエスト上限数 | 1IPアドレスあたり | 200リクエストまで |
| 6 | レート制限 | 1IPアドレスあたり | 20秒につき100リクエストまで |
| 7 | 同時接続上限数 | 1アカウントあたり | 5リクエストまで |
| 8 | タイムアウト | 1リクエストあたり | 60秒まで |
リクエスト共通仕様
全てのb→dash APIは下記の形式でリクエストしてください。
〇リクエストメソッド
| HTTPメソッド | 用途 |
| GET | リソースの取得 |
| POST |
リソースの登録
リソースの登録/更新が混在する処理 アクセストークンの取得 その他処理 |
| PUT | リソースの更新 |
| DELETE | リソースの削除 |
〇リクエストヘッダ
| 項目 | 形式 |
| Content-Type | application/json charset=UTF-8 |
ステータスコード共通仕様
b→dash APIのリクエストに対するレスポンスは、下記のステータスコードが記載されてます。
〇情報レスポンス(100番台)
| コード | 意味 | 説明 |
| 100 | Continue |
継続
クライアントはリクエストを継続できる状態 |
| 101 | Switching Protocol |
プロトコル切替
サーバはリクエストを理解し、 遂行のためにプロトコルの切り替えを要求している状態 |
| 102 | Processing (WebDAV) |
処理中
処理が継続されて行われている状態 (WebDAVの拡張ステータスコード) |
| 103 | Early Hints |
処理中
最終的なレスポンスヘッダが確定する前に、先に予想されるヘッダを伝達している状態 |
〇成功レスポンス(200番台)
| コード | 意味 | 説明 |
| 200 | OK |
GET:成功
POST:認証APIでのアクセストークンの取得に成功 |
| 201 | Created | POST/PUT:サーバ処理が成功で完了して、レスポンスにリソースのURIを含められる状態 |
| 202 | Accepted | リクエスト受付成功、サーバ処理は未完了の状態 |
| 204 | No Content | DELETE:サーバ処理が成功で完了 |
〇クライアントエラーレスポンス(400番台)
| コード | 意味 | 説明 |
| 400 | Bad request | 不正なリクエスト |
| 401 | Unauthorized | 認証に失敗 |
| 403 | Forbidden | アクセス権がない |
| 404 | Not Found | リソースが発見できない |
| 412 | Precondition Failed | サーバー側で適合しない前提条件が、 クライアント側のヘッダーに含まれている |
| 413 | Payload Too Large | リクエストの本体がサーバーで定めている上限を超えている |
| 414 | URI Too Long | リクエストした URI が、サーバーで扱える長さを超えている |
| 415 | Unsupported Media Type | リクエストされたデータのメディア形式をサーバーが対応していない |
| 416 | Range Not Satisfiable | リクエスト内の Range ヘッダー項目で指定された範囲を満たすことができない |
| 425 | Too Early | サーバーが、繰り返される可能性のあるリクエストを拒否 |
| 429 | Request Limit Exceeded | APIコール数(使用制限)の超過 |
〇サーバーエラーレスポンス(500番台)
| コード | 意味 | 説明 |
| 500 | Internal Server Error | サーバー側で処理方法が不明な事態が発生 |
| 502 | Bad Gateway | サーバーが無効なレスポンスを受け取った |
エラー発生時のレスポンス
b→dash APIのリクエストに対するエラー発生時のレスポンスは、下記のステータスコードが記載されてます。
〇レスポンスボディパラメータ
| パラメータ名 | Key | データ型 | 説明 |
| 階層1:result | object | - | |
| 階層2:code | integer($int32) | ステータスコード | |
| 階層2:errors | object[] | エラーの配列 | |
| 階層3:message | string | エラーメッセージ |
〇レスポンスボディサンプル
{
"result": {
"code": 400,
"errors": [
{
"messsage": "Account not found."
}
]
}
}
〇エラーメッセージ
| コード | エラーメッセージ | 説明 |
| 400 | Account not found. | 指定したアカウントが存在しない |
| 401 | Authentication error by header incorrect. | Header不正による認証エラー |
| 400 | The size of the request body exceeds the maximum size permitted. | リクエストボディのサイズが超過 |
| 403 | Do not have permission to access. | アクセス権がない |
| 404 | Resource not found. | リソースが発見できない |
| 412 | Client header precondition do not match server side. | サーバー側で適合しない前提条件が、クライアント側のヘッダーに含まれている |
| 413 | The request payload is larger than the server is willing or able to process. | リクエストの本体がサーバーで定めている上限を超えている |
| 414 | The request is longer than the server is willing to interpret. | リクエストした URI が、サーバーで扱える長さを超えている |
| 415 | The media format of the requested data is unsupported on the server. | リクエストされたデータのメディア形式をサーバーが対応していない |
| 416 | The server cannot provide the requested range. | リクエスト内の Range ヘッダー項目で指定された範囲を満たすことができない |
| 425 | The server refused the request that might be replayed. | サーバーが、繰り返される可能性のあるリクエストを拒否している |
| 429 | API usage limit exceeded. | APIコール数(使用制限)を超過している |