共通仕様
アバウトミーβから提供しているAPIについて共通項目と、エラーについて詳しくご説明します。
要求メッセージ
要求メッセージの形式について説明します。
- パラメータはフォームパラメータ形式です。
- リクエストパラメータの文字コードは「UTF-8」です。
- クライアントは要求メッセージをGETまたはPOSTメソッドを使って送信します。
応答メッセージ
応答メッセージの共通部分の構造を以下に示します。
- レスポンスデータの文字コードは「UTF-8」です。
- フォーマットはXMLとなっています。
- Root要素はresponseです。responseには以下の二つの要素を含みます。
| パラメータ | 説明 |
|---|---|
| status | レスポンスのステータスコード(code)、ステータスメッセージ(message)、言語情報(language)を示します。ステータスについてはステータスコードを参照してください。 |
| result | 結果をセットします。内容はAPI毎に個別に規定されているので、各APIの説明をご参照ください。 |
以下に応答メッセージの例を示します。
ステータスコード
APIの処理結果として以下の応答ステータスとメッセージを返送します。
また、HTTPの応答ステータスコードにも同じ値が設定されます。
| コード | 説明 | メッセージ |
|---|---|---|
| 成功。 | OK | |
| パラメータの値が不正な場合や、想定されていないパラメータなど、渡されたパラメータがWebサービスで期待されたものと一致しない場合に返されます。メッセージにはエラーの原因を表示します。 | （例：APIのパラメータが不正です。） | |
| リソースへのアクセスを許されていないか、利用制限を超えている場合、利用制限に反した場合に返されます。 | APIの利用が制限されています。 | |
| 指定されたユーザID、質問IDが見つからない場合、またはURLが不正で見つからない場合などに返されます。 | データが見つかりません。 | |
| Webサービス内で問題が発生している場合に返されます。 | 現在APIが利用できません。 |
APIのバージョンについて
- APIのURLは全て「/api/{バージョン番号}/{API固有のパス}」の形になっています。
- 例: http://api.aboutme.jp/api/v1/aboutme/users/search
- 「バージョン番号」はAPI実装のメジャーバージョンを表しています。
- メジャーバージョン内では機能拡張を行いますが、後方互換性(以前の仕様にもとづいたリクエストに対しては、機能拡張後も同様のレスポンスを返す)を確保します。
その他共通仕様
上記以外の共通仕様を説明します。
- ・日付情報には「ISO 8601」形式を使用しています。(例:2007-06-28T06:30:35+09:00)
- ・XMLの要素名に含まれるアルファベットはすべて小文字です。
- ・レスポンス中の任意のXML要素内に出現する子要素は特に明言しない限り順不同となります。
- ・更新順一覧など順序性が重要な場合は仕様を明記します。
