基本情報
本システムのAPIはHTTP RPCスタイルです。
- メソッドのURLは以下のフォーマットです。
https://customdomain.com/api/{method}
- メソッドをコールするときにHTTPSとTLS1.2以上を使用します。
- 全てのリクエストをHTTP POSTとして送信します。
Content-type
HTTPヘッダーをapplication/json
に設定し、 認証tokenのリクエストを例外として全てのArgumentをJSONとして送ります。- Tokenをbearer tokenとし
Authorization
のHTTPヘッダーに送信します。Tokenは用意されたBearer
という文字列を持っていますので注意が必要です。BearerはOAuth 2.0の認証スキームを意味しています。
リクエストの例:
POST /api/example.method
Content-type: application/json
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
{"example":"request"}
全てのレスポンスは常にトップレベルstatus
プロパティを含んだJSONオブジェクトとなります。このプロパティはsuccess
あるいはerror
となります。error
のステータスは、システムが読み込むことができるエラーコードのerror
プロパティです。 success
のステータスには、data
プロパティも存在します。data
プロパティの形はそれぞれのメソッドの説明に記載されています。
{
"status": "success",
"data": {
"property": "value"
}
}
{
"status": "error",
"error": "not_found"
}
ページ分割
各メソッドの説明に、ページ分割を利用していると書かれていた場合、データのArrayにそのページの結果と次のページへのカーソル(レスポンスのdata部分にあるnextというプロパティ)が戻されます。デフォルトでは、全てのページ分割のレスポンスは100件の結果を返します。
ページ分割を使用する全てのメソッドは以下に沿って動作します。
- リクエストには
next
は任意です。リクエストのbodyにnext
プロパティが含まれていない場合、最初のページが返されます。 - レスポンスには
next
は任意です。next
の属性として、レスポンスがnull
を返した場合は、これ以上取得するページがないことを意味しています。 - 次のページのデータを取得するためには、同じパラメーターと前のレスポンスで受け取った
next
カーソルを新しいリクエストとして送ります。もし同じパラメーターではない場合、正確な結果を受け取ることができない可能性があります。 - 最後のページは各ページの結果の最大数よりも少ない結果となることがあります。
- 最初のページが最後のページとなることがあります。
- 特定の条件では最後のページが空欄のArrayとなる可能性があります。
- カーソルは短期間で失効します。保管したり、再利用することはできません。
例
最初のページを取得するリクエスト
{
"search": "検索する語句"
}
次のページのカーソルが存在する場合のレスポンス
{
"status": "success",
"data": {
"results": ["結果1", "結果2"],
"next": "RGVRt1m9DRWp"
}
}
次のページのカーソルを含めたリクエスト
{
"search": "検索する語句",
"next": "RGVRt1m9DRWp"
}
最後のページのレスポンス
{
"status": "success",
"data": {
"results": ["結果1", "結果2"],
"next": null
}
}
空欄のページのレスポンス
{
"status": "success",
"data": {
"results": [],
"next": null
}
}
各メソッドの説明では、何のパラメーターが受け入れられるのか、そして何のデータが返されるのかを表しています。
レート制限
全てのメソッドはユーザーに最良のエクスペリエンスを提供するためにレート制限に依存します。全てのレート制限はクライアントIDごとになっています。デフォルトでは、10秒間で100リクエストに制限されています。
レート制限を超えた場合、HTTP 429 Too Many Requests
のHTTPステータスコードとRetry-After
のHTTPヘッダーが返されます。Retry-After
のHTTPヘッダーには再度リクエストが可能になるまでの秒数が含まれています。
上記と同時に以下のレスポンスも返されます。
{
"status": "error",
"error": "rate_limit_exceeded"
}
ペイロード制限
全てのメソッドはリクエストbodyに長さの制限があります。もしペイロードが100KBを超えた場合、400 Bad Request
が以下のレスポンスと共に返されます。
{
"status": "error",
"error": "payload_limit_exceeded"
}
共通エラー
各メソッドの説明にはそのメソッド特有のエラーが記載されています。以下のエラーは各メソッドで発生する可能性のある共通エラーです。
コード | 説明 |
---|---|
invalid_arguments | 指定されたArgumentは無効です。 |
unexpected_error | 予期しないエラーが発生しました。 |
認証エラー
認証に関わるエラーのレスポンスは以下に記載されているOAuth 2.0の仕様に従います。https://tools.ietf.org/html/rfc6750#section-3.1
認証→