API入門ガイド

SURP MDM APIを使用して、プログラムからマスターデータにアクセスする方法を説明します。

📋 概要

SURP MDM APIは、マスターデータ管理システムへのプログラマティックアクセスを提供します。RESTful APIを採用しており、JSON形式でデータをやり取りします。

基本情報

  • ベースURL: https://mdm.surp.tech/api/v1
  • プロトコル: HTTPS
  • 認証方式: APIキーベース認証（Bearer Token）
  • データ形式: JSON
  • 文字エンコーディング: UTF-8

🎯 前提条件

必要なプラン

すべてのプランでAPIを利用できますが、レート制限が異なります:

プランレート制限（分）レート制限（日）
Free10リクエスト100リクエスト
Starter30リクエスト1,000リクエスト
Professional60リクエスト10,000リクエスト
Enterprise無制限無制限

必要な権限

  • APIキーを作成するには Admin ロールが必要です

🔑 APIキーの取得

ステップ1: APIキー作成画面を開く

  1. SURP MDM管理画面にログイン（Admin ロール）
  2. 設定 > APIキー を開く
  3. 「新規APIキー作成」 をクリック

ステップ2: APIキー情報を入力

  1. 以下を入力:

    • キー名: APIキーの用途（例: データ同期用, レポート生成用）
    • 説明: 詳細な説明（任意）
    • スコープ: 必要な権限を選択
      • ✅ read: データの読み取り
      • ✅ write: データの作成・更新
      • ✅ delete: データの削除
    • 有効期限: キーの有効期限（推奨: 1年）

  2. 「作成」をクリック

ステップ3: APIキーを保存

⚠️ 重要: APIキーは作成時に一度だけ表示されます。必ず安全な場所に保存してください。

例:

surp_live_a1b2c3d4e5f6...your_api_key_here

紛失した場合は、新しいAPIキーを作成する必要があります。

🚀 最初のAPIリクエスト

マスター定義の取得

システムに登録されているマスター定義を取得します。

cURLの例

curl -X GET "https://mdm.surp.tech/api/v1/definitions" \
  -H "Authorization: Bearer surp_live_your_api_key_here" \
  -H "Accept: application/json"

レスポンス例

{
  "items": [
    {
      "id": "69ae4965-0ffe-4835-a9bd-b873f5473bd7",
      "tenant_id": "acme-corp",
      "master_type": "department",
      "master_type_label": "部署マスター",
      "schema": {
        "fields": [
          {
            "name": "departmentCode",
            "type": "string",
            "label": "部署コード",
            "required": true,
            "unique": true
          },
          {
            "name": "departmentName",
            "type": "string",
            "label": "部署名",
            "required": true
          }
        ]
      },
      "version": 1,
      "created_at": "2025-10-30T02:30:32.984186Z"
    }
  ],
  "total": 1
}

🔐 認証方法

すべてのAPIリクエストには、AuthorizationヘッダーにAPIキーを含める必要があります。

ヘッダー形式

Authorization: Bearer YOUR_API_KEY

注意: Bearer の後にスペースが必要です。

プログラミング言語別の例

JavaScript (fetch)

const response = await fetch('https://mdm.surp.tech/api/v1/definitions', {
  headers: {
    'Authorization': 'Bearer surp_live_your_api_key_here',
    'Accept': 'application/json'
  }
});
const data = await response.json();

Python (requests)

import requests
 
headers = {
    'Authorization': 'Bearer surp_live_your_api_key_here',
    'Accept': 'application/json'
}
 
response = requests.get('https://mdm.surp.tech/api/v1/definitions', headers=headers)
data = response.json()

PHP

<?php
$ch = curl_init('https://mdm.surp.tech/api/v1/definitions');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer surp_live_your_api_key_here',
    'Accept: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);

📊 スコープと権限

APIキーには、以下のスコープを設定できます:

スコープ一覧

スコープ説明対応するアクション
readデータの読み取りGETリクエスト、データエクスポート
writeデータの作成・更新POST, PUT, PATCH、インポート、承認/却下
deleteデータの削除DELETEリクエスト

HTTPメソッドとスコープの対応

HTTPメソッドアクション必要なスコープ
GETreadread
POSTcreatewrite
PUTupdatewrite
PATCHupdatewrite
DELETEdeletedelete

権限エラー

スコープが不足している場合のエラー:

{
  "detail": "API key missing required scope: write"
}

HTTPステータス: 403 Forbidden

🔄 ページネーション

大量のデータを取得する場合は、ページネーションを使用します。

パラメータ

  • skip: スキップする件数（デフォルト: 0）
  • limit: 取得する件数（デフォルト: 100、最大: 1000）

例

# 最初の100件
curl "https://mdm.surp.tech/api/v1/masters/department?skip=0&limit=100"
 
# 次の100件
curl "https://mdm.surp.tech/api/v1/masters/department?skip=100&limit=100"

⚠️ エラーハンドリング

エラーレスポンスの形式

{
  "detail": "エラーメッセージ"
}

HTTPステータスコード

ステータス説明
200 OK成功
201 Created作成成功
202 Accepted承認リクエスト作成（承認が必要な場合）
400 Bad Requestリクエストが不正
401 Unauthorized認証エラー
403 Forbidden権限エラー
404 Not Foundリソースが見つからない
429 Too Many Requestsレート制限超過
500 Internal Server Errorサーバーエラー

🛡️ レート制限

レート制限の確認

レスポンスヘッダーでレート制限の状況を確認できます:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1635724800

レート制限エラー

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

HTTPステータス: 429 Too Many Requests

💡 ベストプラクティス

1. APIキーの管理

  • 環境変数に保存: コードに直接埋め込まない
  • 読み取り専用スコープ: データ参照のみの場合は read のみ付与
  • 定期的なローテーション: 3〜6ヶ月ごとにAPIキーを再作成

2. エラーハンドリング

すべてのAPIリクエストでエラーハンドリングを実装します:

try {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json();
} catch (error) {
  console.error('API error:', error);
}

3. リトライロジック

レート制限やネットワークエラーの場合、自動的にリトライします:

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        await new Promise(resolve => setTimeout(resolve, 60000)); // 1分待つ
        continue;
      }
      return response;
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

🔗 関連ガイド

📞 サポート

API利用に関する質問は、よくある質問をご覧いただくか、システム管理者にお問い合わせください。