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