リファレンス
APIの詳しい仕様について説明しています。
はじめに
このページでは、APIを利用してデータを参照・更新する方法について解説しています。
エンドポイントについての詳細は各バージョンのページをご覧ください。
リクエスト
このAPIはJSONをやり取りするRestfulなAPIです。
PUT/POST/PATCH といった更新系リクエストの Content-Type には application/json を指定してください。
全てのAPI呼び出しにはアプリケーショントークンによる認証が必要です。アプリケーショントークンは、担当窓口より入手ください。入手後、x-api-key ヘッダに設定してご利用ください。
curl --request GET \
--url 'https://smartdrive-api.com/v1.2/devices/010009/locations?ts_from=2019-01-01T00:00:00Z&ts_to=2019-10-01T00:00:00Z' \
--header 'Content-Type: application/json' \
--header 'x-api-key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
レスポンス
特別な注意書きがない限り、ほとんどのAPIのレスポンスはJSONとなります。
参照系のエンドポイントが /devices のようなコレクションを指し示す場合は、レスポンスの data はリソースの配列になります。
一度のレスポンスでデータが取得しきれない場合は paging プロパティに次の呼び出し時に使うカーソル情報が設定されます。
{
"meta": {
"http_status_code": 200,
"result": true
},
"paging": {
"next": "MTAxNTExOTQ1MjAwNzI5NDE="
},
"data": [
{
"code": "07144A",
"organization": {
"id": "ZrMa7d5WF6cpsV0ejp29",
"name": "SmartDrive"
}
}
]
}
/devices/{device_code} や /devices/{device_code}/last_location のようにリソース自体、もしくはリソースのプロパティを指し示す場合は、レスポンスの data は単一のオブジェクトになります。
{
"meta": {
"http_status_code": 200,
"result": true
},
"data": {
"ts": "2014-06-02T23:02:34Z",
"lat": 35.658581,
"lng": 139.745433,
"speed": 6,
"h_accuracy": 10,
"v_accuracy": 30
}
}
削除・更新のエンドポイントの場合、レスポンスの data は作成・更新されたオブジェクトになります。
{
"meta": {
"http_status_code": 200,
"result": true
},
"data": {
"id": "sV2Wcp9FZrMa7d56p0ej",
"organization": {
"id": "ZrMa7d5WF6cpsV0ejp29",
"name": "SmartDrive"
},
"name": "東京タワー",
"address": "東京都港区芝公園４丁目２−８",
"coordinates": {
"lat": 35.658581,
"lng": 139.745433
},
"radius": 100
}
}
削除のエンドポイントの場合、レスポンスの data は存在しません。
{
"meta": {
"http_status_code": 200,
"result": true
}
}
エラー
APIでエラーが発生した場合は、レスポンスの http_status_code が300以上になります。また、レスポンスの errors プロパティにエラーの詳細が格納されます。
{
"meta": {
"http_status_code": 401,
"result": false
},
"errors": [
{
"code": 401,
"message": "Request unauthorized",
"detail": "Please check that the authentication header is correct."
}
]
}
ページング
リソース一覧を取得・検索するAPIのほとんどは、カーソルベースのページネーションが実装されています。
ページング可能なコレクションリソースにおいて、データ量が多く、一度のAPI呼び出しで全てのデータを取得できないケースでは、レスポンスに paging.next というキー＆バリューが設定されます。
{
"meta": {
"http_status_code": 200,
"result": true
},
"paging": {
"next": "MTAxNTExOTQ1MjAwNzI5NDE="
},
"data": [
{
"code": "07144A",
"organization": {
"id": "ZrMa7d5WF6cpsV0ejp29",
"name": "SmartDrive"
}
}
]
}
次回のAPI呼び出し時にその値を cursor パラメーターに設定することで、残りのデータを取得することができます。
未指定の場合は最初からの取得になります。
curl --location --request GET 'https://smartdrive-api.com/v1.0/devices?cursor=MTAxNTExOTQ1MjAwNzI5NDE=' \
--header 'Content-Type: application/json' \
--header 'x-api-key: APP_TOKEN'
桁数
各データ型について、特別注釈のない場合の取りうる値は下記のとおりになります。
| data type | 取りうる値 | 最大印字文字数 |
|---|---|---|
| float | [-3.4028234663852886e+38, 3.4028234663852886e+38] | 47 |
| double | [-1.7976931348623157e+308, 1.7976931348623157e+308] | 317 |
| boolean | true or false | 5 |
| int32 | [-2147483648, 2147483647] | 11 |
| int64 | [-9223372036854775808, 9223372036854775807] | 20 |