共通仕様
@nifty TimeLineのAPIの要求メッセージや応答メッセージの共通仕様について説明します。
要求メッセージ
要求メッセージの形式について説明します。
- パラメータはフォームパラメータ形式とします。
- リクエストパラメータの文字コードは「UTF-8」とします。
- クライアントは要求メッセージはGETまたはPOSTメソッドを使って送信します。
- データの投稿や削除を行なうAPIにはPOSTのみを受けます。
応答メッセージ
応答メッセージの共通の構造について説明します。
- 応答メッセージはXML形式とします。
- レスポンスデータの文字コードは「UTF-8」とします。
- ルート要素はresponseとします。
- responseには以下の要素を含みます。
| パラメータ | 説明 |
|---|---|
| status | レスポンスのステータスコード(code)、ステータスメッセージ(message)、言語情報(language)を示します。 |
| result | 結果をセットします。内容はAPI毎に個別に規定します。 |
以下に応答メッセージの例を示します。
ステータスコード
APIの処理結果として以下の応答ステータスとメッセージを返送します。また、HTTPの応答ステータスコードにも同じ値を設定します。
| コード | 説明 | メッセージ |
|---|---|---|
| 200 | 成功。 | OK |
| 400 | パラメーターの値が不正な場合や、想定されていないパラメーターなど渡されたパラメータがWebサービスで期待されたものと一致しない場合に返されます。このメッセージは何が間違っているか、何が正しくないかを伝えます。 | （例：APIのパラメータが不正です。） |
| 403 | リソースへのアクセスを許されていないか、利用制限を超えている場合、利用制限に反した場合に返されます。 | APIの利用が制限されています。 |
| 404 | 不正なURLが指定された場合などに返されます。 | データが見つかりません。 |
| 503 | Webサービス内で問題が発生している場合に返されます。 | 現在APIが利用できません。 |
@nifty TimeLine APIキー
認証が必要なAPI(リソースの追加、変更,削除または、閲覧制限のあるリソースの閲覧)では、その利用権限を確認するため、ユーザ対して@nifty TimeLine APIキー(以下、APIキー)の提示を要求します。 APIキーは@nifty TimeLineの登録ユーザに対して発行される、ユーザ毎に一意な値です。アプリケーションはAPIキーが有効なものであることを確認し認証を行ないます。この値を利用者本人以外によって利用できるように公開または貸与しないようにしてください。
APIキーは@nifty TimeLineにログイン後、マイページ上のユーザインタフェース(http://timeline.nifty.com/my_page/apikey)から取得できます。またAPIキーは必要に応じて再発行できます(再発行した場合は、以前のAPIキーは利用できなくなります)。
APIのバージョンについて
APIのバージョン管理のポリシーについて説明します。
- メジャーバージョン内では機能拡張を行ないますが、後方互換性(以前の仕様にもとづいたリクエストに対しては、機能拡張後も同様のレスポンスを返す)を確保します。
- レスポンスのXML要素の出現順は、特に明言しない限り順不同とします。
- 更新順一覧など順序性が重要な場合は仕様に明記します。
- URLの命名規則は「/api/{バージョン番号}/{API固有のパス}」とします。
- 「バージョン番号」はAPI実装のメジャーバージョンとします。(例: http://api.timeline.nifty.com/api/v1/timelines/search)
その他共通仕様
上記以外の共通仕様を示します。
- 日付情報は「ISO 8601」形式とします。(例: 2007-06-28T06:30:35+09:00)
- XMLの要素名に含まれるアルファベットはすべて小文字とします。
