-
Notifications
You must be signed in to change notification settings - Fork 11
PARTAKE Web API
この文書は PARTAKE beta2 の API を解説するものです。
すべての API は、指定された URL を GET リクエストもしくは POST リクエストで叩くことによって利用できます。
API のパラメータは、GET リクエストのときは URI に query string 形式で記述することによって、 または POST リクエストのときは body 部に www-form-urlencoded 形式で記述することによって 渡すことができます。
大半の API は、GET もしくは POST メソッドのどちらかのみを受け付けます。これは標準的なウェブの規約に従っており、 情報を取得するリクエストは GET メソッドを、サーバーの情報を変更するリクエストは POST メソッドを用います。
POST リクエストは、通常 sessionToken と呼ばれる string 型の値が必須になっています。 これは CSRF を防ぐためのトークンで、/api/account/sessionToken から取得でき、ここから取得したものと同じ文字列を 送らなければなりません。sessionToken はセッションの有効期間中は常に同じ値であるため、一度取得してしまえば セッションが無効にならない限り再利用できます。
すべての返答は、text/json 形式で返されます。現状リクエスト時に Accepts ヘッダーを指定しても、常に text/json 形式 で返答されますが、この仕様は変更されることがあります。例えば application/xml 形式でも返答できるように改良される かもしれません。常に text/json が必要なユーザーは、リクエスト時に Accepts ヘッダーを text/json に明示的に 指定するべきです。
PARTAKE はセッションの維持のために、クッキーを発行します。クライアントはクッキーを適切に処理することが 求められます。
API は、成功・不成功をすべて HTTP のステータスコードを利用して返します。主なステータスコードは次のとおりです。
| ステータスコード | ステータス | 意味 |
|---|---|---|
| 200 | OK | リクエストを理解し、サーバーは正しく応答した。 |
| 400 | Bad Request | リクエストに不備がある。 |
| 401 | Unauthorized | ログインが必要な API に、ログイン無しでアクセスした。 |
| 403 | Forbidden | この API を利用する権限がない。 |
| 500 | Internal Server Error | サーバー内部でエラーが発生した。 |
4xx 番代のステータスコードはユーザーのリクエストに誤りがあり、5xx 番代のステータスコードはサーバー側でなんらかの エラーが発生したことを示します。また、リダイレクトのために 3xx 番代のステータスコードが返却される場合があります。 これらは全てウェブの標準に則っており、クライアントは標準に沿った動作をすることが期待されています。
PARTAKE はエラーを返却する場合、reason というキーが含まれる json を返却します。 reason の値は string で、は自然言語で書かれたエラーの詳細が記述されます。 場合によっては additionalInfo というキーを含み、さらに詳細な理由が説明されます。
なお、この API のレスポンスとして指定されていないフィールドが返却値に含まれていることがありますが、 そのフィールドは将来予告なく削除されることがあります。
API で用いられる型に関しては次のページを参照してください。
API は次のページを参照してください。