このページでは、ATLAS-Things APIの仕様詳細について記載しています。

---

ATLAS-Things APIとは

ATLAS-Things APIを使うことで、各種入出荷実績を記録・管理することができます。 API機能として入出荷実績データの登録・出力、ログ収集などを保持しています。

---

ATLAS-Things APIご利用開始方法

ATLAS-Things APIのご利用には、アカウント登録の申請が必要です。
右記連絡先まで申請のご連絡をお願いします。

---

API認証について

APIの認証には、API Keyと JWT(JSON Web Token)を使用します。

JWTの生成方法

本サービスのアカウント登録後、クライアントごとにAPI KeyとAPI Secretを発行します。
JWTの生成には、API Secretを使用します。

JWTのペイロードとして、以下の形式のJSONオブジェクト(UTF-8)を生成します。 requestDateは、APIをリクエストしたシステム日時(ISO8601拡張形式の年月日時分秒までのUTC)を設定してください。
JWTの有効期限は1分間なので、リクエストの都度、設定することをお勧めします。

            {
              'requestDate': '2019-03-01T11:20:52Z'
            }

生成したペイロードをbase64urlエンコードし、API Secretを鍵にしてJWTを生成します。
暗号化アルゴリズムは、HMAC SHA-256を指定してください。

C#の場合のJWTの実装例

.Net FrameworkのパッケージマネージャであるNuGetにアクセスして、System.IdentityModel.Tokens.Jwtをインストールします。

            using System;
            using System.IdentityModel;
            
            class Example
            {
              // API Secret(本サービスのアカウント登録後に発行)
              var apiSecret = "example-api-secret";
            
              // JWTを操作するクラスを用意
              var handler = new JwtSecurityTokenHandler();
            
              // 共通鍵の生成
              var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(apiSecret));
            
              // 署名情報を生成(暗号化アルゴリズムはHMAC SHA-256を指定)
              var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");
            
              // JWTヘッダの生成
              var header = new System.IdentityModel.Tokens.Jwt.JwtHeader(credentials);
            
              // ペイロードの生成
              var payload = new System.IdentityModel.Tokens.Jwt.JwtPayload
              {
                { "requestDate", DateTime.UtcNow.ToString("u").Replace(" ","T") }
              }
            
              // JWTの生成
              var secToken = new System.IdentityModel.Tokens.Jwt.JwtSecurityToken(header, payload);
              var jwt = handler.WriteToken(secToken);
            }

API認証に必要な情報

クライアントは、API KeyとJWTをリクエストに含めて送信することで、APIの認証をします。

下記の表が、リクエストに含まれる認証情報です。
X-ATLAS-API-KeyヘッダーとAuthorizationヘッダーを、全てのAPIのリクエストに必ず含めてください。

parameters	in	data type	description
X-ATLAS-API-Key	header	string	API Keyを設定するヘッダー
Authorization	header	string	JWTを設定するヘッダー

API認証失敗時

認証に失敗した場合、エラー情報がクライアントに返ります。
エラー情報を確認のうえ、正しい認証情報を設定して再度リクエストしてください。

HTTP status code	errorCode	detail	description
401 Unauthorized	800	authorization failed.	その他の認証エラー
	801	jwt expired.	JWTの有効期限切れエラー
	804	requestDate is invalid format.	JWTのリクエスト日時のフォーマットエラー

---

APIのリクエストについて

各APIのリクエストは、すべての項目を含めて送信する必要があります。
必須でない項目で設定が不要な場合は、値にNULLを設定してください。
リクエストとして定義されている項目が存在しない場合、エラー情報が返ります。

---

例外的なHTTPステータス

本サービスでは規定のHTTPステータス以外のレスポンスが返ることがあります。

403(Forbidden)

APIのエンドポイントが正しくない場合、HTTP status codeは403(Forbidden)になります。
その場合後述するエラーレスポンスではなく、下記のようにmessageのみが返ります。

            {
              'message': 'Forbidden'
            }

500(Internal Server Error)

APIで問題が発生した場合、HTTP status codeは500(Internal Server Error)になります。
その場合後述するエラーレスポンスではなく、下記のようにmessageのみが返ります。

            {
              'message': 'Internal Server Error'
            }

これは本サービスの問題ではなく、クラウドプラットフォームの一時的な問題です。 少し時間をおいてからリトライしてください。複数回同じステータスになる場合はお問い合わせください。

504(Gateway Timeout)

APIがタイムアウトした場合、HTTP status codeは504(Gateway Timeout)になります。
その場合後述するエラーレスポンスではなく、下記のようにmessageのみが返ります。

            {
              'message': 'Endpoint request timed out'
            }

これは本サービスの問題ではなく、クラウドプラットフォームの一時的な問題です。 少し時間をおいてからリトライしてください。複数回同じステータスになる場合はお問い合わせください。

---

メンテナンスについて

本サービスがメンテナンス中の場合、すべての API リクエストで HTTP ステータス 503 が返ります。 一定時間経過後にリトライするようにしてください。

            {
              'title': 'ServiceUnavailable',
              'errorCode': '901',
              'detail': 'system maintenance.',
              'traceId': '',
              'invalidParams': []
            }

https://api.atlas-things.io/v1