概要
はじめに
ご利用方法
本管理画面よりAPIキーを発行する必要があります。APIキーの発行は管理用ユーザ詳細画面より行うことができます。
一般注記事項
API URL
本APIは以下URLをベースに利用します。
https://secure.sakura.ad.jp/rs/admin/api/認証
本APIは、APIキーとシークレットトークンを利用したBasic認証を使用します。
APIキーとシークレットトークンは、管理用ユーザ詳細画面で発行できます。
認可
各リソースの操作にはAPIキーに紐付いた管理用ユーザに操作したい内容の特権が必要です。
REST API
本APIはRESTベースのAPIとなっており、リクエストやレスポンスのフォーマットの多くにJSON形式を使用しています。
文字コード
文字コードはUTF-8を使用しています。
型
本APIのデータには以下の型があります。
| 型 | 説明 | 例 |
|---|---|---|
| string | 文字列 |
"foo"
|
| integer | 整数 |
"42"
|
| boolean | 真偽値 |
"0" または "1"
|
| datetime | 日付 |
"2000-01-01T00:00:00+09:00"
|
| array | 配列 |
["foo","bar"]
|
| object | オブジェクト |
{"foo":"bar"}
|
注意事項
短期間に集中したアクセスはしないでください。
リソースを複数作成される場合は、個々のリソースの作成が完了してから次のリソースを作成するようにしてください。
APIレスポンス
HTTPステータスコード
本APIは以下で列挙されるHTTPレスポンスコードを返します。
| ステータスコード | 説明 |
|---|---|
| 200 OK | 正常に処理され、何らかのレスポンスが返却された。 |
| 201 Created | 正常に処理され、何らかのリソースが作成された。 |
| 204 No Content | 正常に処理され、空のレスポンスが返却された。 |
| 400 Bad Request | リクエストパラメータが不正など。 |
| 401 Unauthorized | 認証に失敗した。 |
| 403 Forbidden | リソースへのアクセス権がない。 |
| 404 Not Found | リソースが存在しない、または指定メソッドに対応していない。 |
| 422 Unprocessable Entity | バリデーションエラーなど処理できない値が渡された。 |
| 500 Internal Server Error | 内部エラーが発生した。 |
| 503 Service Unavailable | 何らかの事情によりサービスが利用可能でない。 |
レスポンスボディ
レスポンスボディを返すとき、トップレベルに以下のうち少なくとも1つを持つJSON形式のオブジェクトを返します。
| キー | 説明 |
|---|---|
| data | リソースオブジェクトやその配列、または null。 |
| meta | ページ情報などのメタデータ。 |
| errors | エラーオブジェクトの配列。 |
例
{
"data": [
<Resource Object>,
<Resource Object>,
..
],
"meta": {
"page": {
"size": 10,
"number": 1,
"total": 42
}
}
}リソースオブジェクト
リソース情報を表すオブジェクトで、以下のいずれか、または複数のキーを持ちます。
| キー | 型 | 説明 |
|---|---|---|
| type | string | リソース種別 |
| id | string | リソースID |
| attributes | object | リソースの持つ値。 |
| relationships | object | リソースのリレーション。 |
例
{
"type": "accounts",
"id": "1",
"attributes": {
"customer_id": "foo",
"comment": ...
},
"relationsihps": {
"server": {
"data": {
"type": "servers",
"id": "1"
}
}
}
}エラー
エラーが発生した場合、可能であればトップレベルのキーに errorsキーを含んだエラーオブジェクトの配列をかえします。
エラーオブジェクトは以下のいずれか、またはすべてのキーを持ちます。
| キー | 型 | 説明 |
|---|---|---|
| code | string | 該当するエラーのコード。 必ず含まれる。 |
| status | string | 該当するHTTPステータスコード。 必ず含まれる。 |
| source | object |
下記のいずれかのキーを含む、エラーへの参照を含むオブジェクト。
|
| detail | string | 人が読むことを前提としたエラーメッセージ。 |
例
{
"errors": [
{
"code": "INVALID_ATTRIBUTE",
"status": 422,
"source": {
"pointer": "/data/attributes/foo"
},
"detail": "fooは○○できません。"
}
]
}「リソースの検索」共通インタフェース
リクエストパラメータの共通仕様
リクエストパラメータはURLのクエリストリングとして指定します。
GET /path/to/resources?filter[name]=foo&page[size]=5 HTTP/1.1ページング
リソースの検索では、以下パラメータを使用して検索結果の取得範囲を限定できます。
リソースによっては、取得可能な最大数が決まっており、それを超えた数を一度に取得することができません。
| 名前 | 型 | 説明 | 例 |
|---|---|---|---|
| size | integer | ページサイズ。
1ページで取得する数。 |
5
|
| number | integer | ページ番号。
取得するページ数。 |
1
|
| limit | integer | ページリミット。
1ページで取得する最大数。 |
5
|
| offset | integer | オフセット。
取得を開始する件数。 |
1
|
フィルタリング
filterパラメータを利用して取得するリソースを絞り込むことができます。
フィルタリングの条件は各リソースの説明を確認してください。
レスポンスの共通仕様
「リソースの検索」インタフェースを持つAPIが返すレスポンスは、以下の様なオブジェクト構造を持ちます。
{
"data": [
<Resource Object>,
<Resource Object>,
..
],
"meta": {
"page": {
"size": 10,
"number": 1,
"total": 42
}
}
}リソース取得(GET)
レスポンスの共通仕様
「リソース取得」インタフェースを持つAPIが返すレスポンスは、以下の様なオブジェクト構造を持ちます。
{
"data": {
"type": "resources",
"id": "1",
"attributes": {
"foo": "bar",
"baz": ...
}
}
}リソース登録(POST)
リクエストパラメータの共通仕様
「リソース登録」では、JSON形式で作成したいオブジェクトのデータを指定します。
{
"data": {
"type": "resources",
"attributes": {
"foo": "bar",
"baz": ...
},
"relationships": {
"relation-name": {
"type": "related-resource-name",
"id": "1"
}
}
}
}
他リソースのリレーションが必要な場合、reationshipsオブジェクトにリソースオブジェクトを設定します。
レスポンスの共通仕様
「リソース取得」インタフェースを持つAPIが返すレスポンスは、以下の様なオブジェクト構造を持ちます。
{
"data": {
"type": "resources",
"id": "1",
"attributes": {
"foo": "bar",
"baz": ...
},
"links": {
"self": "https://secure.sakura.ad.jp/rs/admin/api/resources/1"
}
}
}リソース設定(PATCH)
リクエストパラメータの共通仕様
「リソース設定」では、JSON形式で作成したいオブジェクトのデータを指定します。
{
"data": {
"type": "resources",
"id": "1",
"attributes": {
"foo": "bar",
"baz": ...
}
}
}attributesには、変更を行う値のみを指定することができます。
レスポンスの共通仕様
「リソース取得」インタフェースを持つAPIが返すレスポンスは、以下の様なオブジェクト構造を持ちます。
{
"data": {
"type": "resources",
"id": "1",
"attributes": {
"foo": "bar",
"baz": ...
}
}
}リソース削除(DELETE)
レスポンスの共通仕様
リソースの削除に成功した場合、204のステータスを返し、レスポンスボディは返しません。