SDK ドキュメント

概要

開発者がサービスを迅速に統合できるよう、複数のプログラミング言語向けのSDKを提供しています。このドキュメントでは、すべての公式SDKのインストール、設定、使用方法について説明します。

サポートされているSDK

JavaScript/TypeScript SDK

インストール

# npm
npm install @yourapp/sdk

# yarn
yarn add @yourapp/sdk

# pnpm
pnpm add @yourapp/sdk

基本的な使用方法

import { YourAppSDK } from '@yourapp/sdk';

// SDKの初期化
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  environment: 'production', // または 'sandbox'
  timeout: 30000
});

// ユーザー管理
const user = await sdk.users.create({
  email: 'user@example.com',
  name: 'John Doe'
});

// プロジェクト管理
const project = await sdk.projects.create({
  name: 'My Project',
  description: 'プロジェクトの説明'
});

// ファイルアップロード
const file = await sdk.files.upload({
  file: fileBuffer,
  filename: 'document.pdf',
  projectId: project.id
});

TypeScript サポート

import { YourAppSDK, User, Project, CreateUserRequest } from '@yourapp/sdk';

const sdk = new YourAppSDK({
  apiKey: process.env.YOURAPP_API_KEY!,
  environment: 'production'
});

// 型安全なユーザー作成
const createUser = async (userData: CreateUserRequest): Promise<User> => {
  return await sdk.users.create(userData);
};

// 型安全なプロジェクト取得
const getProjects = async (): Promise<Project[]> => {
  return await sdk.projects.list({
    limit: 10,
    offset: 0
  });
};

Python SDK

インストール

pip install yourapp-sdk

基本的な使用方法

from yourapp_sdk import YourAppSDK
from yourapp_sdk.exceptions import YourAppError

# SDKの初期化
sdk = YourAppSDK(
    api_key='your-api-key',
    environment='production',
    timeout=30
)

try:
    # ユーザー作成
    user = sdk.users.create({
        'email': 'user@example.com',
        'name': 'John Doe'
    })
    
    # プロジェクト作成
    project = sdk.projects.create({
        'name': 'My Project',
        'description': 'プロジェクトの説明'
    })
    
    # ファイルアップロード
    with open('document.pdf', 'rb') as file:
        uploaded_file = sdk.files.upload(
            file=file,
            filename='document.pdf',
            project_id=project['id']
        )
        
except YourAppError as e:
    print(f"エラーが発生しました: {e}")

非同期サポート

import asyncio
from yourapp_sdk import AsyncYourAppSDK

async def main():
    sdk = AsyncYourAppSDK(
        api_key='your-api-key',
        environment='production'
    )
    
    # 非同期でユーザー作成
    user = await sdk.users.create({
        'email': 'user@example.com',
        'name': 'John Doe'
    })
    
    # 非同期でプロジェクト一覧取得
    projects = await sdk.projects.list(limit=10)
    
    await sdk.close()

# 実行
asyncio.run(main())

Java SDK

インストール

Maven:

<dependency>
    <groupId>com.yourapp</groupId>
    <artifactId>yourapp-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle:

implementation 'com.yourapp:yourapp-sdk:1.0.0'

基本的な使用方法

import com.yourapp.sdk.YourAppSDK;
import com.yourapp.sdk.models.User;
import com.yourapp.sdk.models.Project;
import com.yourapp.sdk.exceptions.YourAppException;

public class Example {
    public static void main(String[] args) {
        // SDKの初期化
        YourAppSDK sdk = new YourAppSDK.Builder()
            .apiKey("your-api-key")
            .environment("production")
            .timeout(30000)
            .build();
        
        try {
            // ユーザー作成
            User user = sdk.users().create(
                User.builder()
                    .email("user@example.com")
                    .name("John Doe")
                    .build()
            );
            
            // プロジェクト作成
            Project project = sdk.projects().create(
                Project.builder()
                    .name("My Project")
                    .description("プロジェクトの説明")
                    .build()
            );
            
            // ファイルアップロード
            File file = new File("document.pdf");
            UploadedFile uploadedFile = sdk.files().upload(
                file,
                "document.pdf",
                project.getId()
            );
            
        } catch (YourAppException e) {
            System.err.println("エラーが発生しました: " + e.getMessage());
        }
    }
}

C# SDK

インストール

dotnet add package YourApp.SDK

基本的な使用方法

using YourApp.SDK;
using YourApp.SDK.Models;
using YourApp.SDK.Exceptions;

class Program
{
    static async Task Main(string[] args)
    {
        // SDKの初期化
        var sdk = new YourAppSDK(new YourAppSDKOptions
        {
            ApiKey = "your-api-key",
            Environment = "production",
            Timeout = TimeSpan.FromSeconds(30)
        });
        
        try
        {
            // ユーザー作成
            var user = await sdk.Users.CreateAsync(new CreateUserRequest
            {
                Email = "user@example.com",
                Name = "John Doe"
            });
            
            // プロジェクト作成
            var project = await sdk.Projects.CreateAsync(new CreateProjectRequest
            {
                Name = "My Project",
                Description = "プロジェクトの説明"
            });
            
            // ファイルアップロード
            using var fileStream = File.OpenRead("document.pdf");
            var uploadedFile = await sdk.Files.UploadAsync(
                fileStream,
                "document.pdf",
                project.Id
            );
        }
        catch (YourAppException ex)
        {
            Console.WriteLine($"エラーが発生しました: {ex.Message}");
        }
    }
}

Go SDK

インストール

go get github.com/yourapp/sdk-go

基本的な使用方法

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    
    "github.com/yourapp/sdk-go"
)

func main() {
    // SDKの初期化
    client := yourapp.NewClient(&yourapp.Config{
        APIKey:      "your-api-key",
        Environment: "production",
        Timeout:     30,
    })
    
    ctx := context.Background()
    
    // ユーザー作成
    user, err := client.Users.Create(ctx, &yourapp.CreateUserRequest{
        Email: "user@example.com",
        Name:  "John Doe",
    })
    if err != nil {
        log.Fatalf("ユーザー作成エラー: %v", err)
    }
    
    // プロジェクト作成
    project, err := client.Projects.Create(ctx, &yourapp.CreateProjectRequest{
        Name:        "My Project",
        Description: "プロジェクトの説明",
    })
    if err != nil {
        log.Fatalf("プロジェクト作成エラー: %v", err)
    }
    
    // ファイルアップロード
    file, err := os.Open("document.pdf")
    if err != nil {
        log.Fatalf("ファイル読み込みエラー: %v", err)
    }
    defer file.Close()
    
    uploadedFile, err := client.Files.Upload(ctx, &yourapp.UploadRequest{
        File:      file,
        Filename:  "document.pdf",
        ProjectID: project.ID,
    })
    if err != nil {
        log.Fatalf("ファイルアップロードエラー: %v", err)
    }
    
    fmt.Printf("ファイルがアップロードされました: %s\n", uploadedFile.ID)
}

PHP SDK

インストール

composer require yourapp/sdk

基本的な使用方法

<?php
require_once 'vendor/autoload.php';

use YourApp\SDK\YourAppSDK;
use YourApp\SDK\Exceptions\YourAppException;

// SDKの初期化
$sdk = new YourAppSDK([
    'api_key' => 'your-api-key',
    'environment' => 'production',
    'timeout' => 30
]);

try {
    // ユーザー作成
    $user = $sdk->users->create([
        'email' => 'user@example.com',
        'name' => 'John Doe'
    ]);
    
    // プロジェクト作成
    $project = $sdk->projects->create([
        'name' => 'My Project',
        'description' => 'プロジェクトの説明'
    ]);
    
    // ファイルアップロード
    $uploadedFile = $sdk->files->upload([
        'file' => fopen('document.pdf', 'r'),
        'filename' => 'document.pdf',
        'project_id' => $project['id']
    ]);
    
    echo "ファイルがアップロードされました: " . $uploadedFile['id'] . "\n";
    
} catch (YourAppException $e) {
    echo "エラーが発生しました: " . $e->getMessage() . "\n";
}
?>

Ruby SDK

インストール

gem install yourapp-sdk

基本的な使用方法

require 'yourapp-sdk'

# SDKの初期化
sdk = YourApp::SDK.new(
  api_key: 'your-api-key',
  environment: 'production',
  timeout: 30
)

begin
  # ユーザー作成
  user = sdk.users.create(
    email: 'user@example.com',
    name: 'John Doe'
  )
  
  # プロジェクト作成
  project = sdk.projects.create(
    name: 'My Project',
    description: 'プロジェクトの説明'
  )
  
  # ファイルアップロード
  File.open('document.pdf', 'rb') do |file|
    uploaded_file = sdk.files.upload(
      file: file,
      filename: 'document.pdf',
      project_id: project[:id]
    )
    
    puts "ファイルがアップロードされました: #{uploaded_file[:id]}"
  end
  
rescue YourApp::SDK::Error => e
  puts "エラーが発生しました: #{e.message}"
end

共通機能

認証

すべてのSDKは以下の認証方法をサポートしています：

APIキー認証

// JavaScript
const sdk = new YourAppSDK({
  apiKey: 'your-api-key'
});

# Python
sdk = YourAppSDK(api_key='your-api-key')

OAuth 2.0

// JavaScript
const sdk = new YourAppSDK({
  oauth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'https://your-app.com/callback'
  }
});

// アクセストークンの取得
const token = await sdk.auth.getAccessToken(authorizationCode);

JWT認証

// JavaScript
const sdk = new YourAppSDK({
  jwt: {
    secret: 'your-jwt-secret',
    algorithm: 'HS256'
  }
});

エラーハンドリング

JavaScript/TypeScript

import { YourAppSDK, YourAppError, ValidationError, NetworkError } from '@yourapp/sdk';

try {
  const user = await sdk.users.create(userData);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('バリデーションエラー:', error.details);
  } else if (error instanceof NetworkError) {
    console.error('ネットワークエラー:', error.message);
  } else if (error instanceof YourAppError) {
    console.error('APIエラー:', error.message, error.code);
  } else {
    console.error('予期しないエラー:', error);
  }
}

Python

from yourapp_sdk.exceptions import (
    YourAppError,
    ValidationError,
    NetworkError,
    AuthenticationError
)

try:
    user = sdk.users.create(user_data)
except ValidationError as e:
    print(f"バリデーションエラー: {e.details}")
except NetworkError as e:
    print(f"ネットワークエラー: {e}")
except AuthenticationError as e:
    print(f"認証エラー: {e}")
except YourAppError as e:
    print(f"APIエラー: {e.message} (コード: {e.code})")

ページネーション

JavaScript/TypeScript

// 基本的なページネーション
const projects = await sdk.projects.list({
  limit: 20,
  offset: 0
});

// カーソルベースのページネーション
let cursor = null;
const allProjects = [];

do {
  const response = await sdk.projects.list({
    limit: 100,
    cursor: cursor
  });
  
  allProjects.push(...response.data);
  cursor = response.nextCursor;
} while (cursor);

Python

# ジェネレーターを使用した自動ページネーション
for project in sdk.projects.list_all(limit=100):
    print(f"プロジェクト: {project['name']}")

# 手動ページネーション
offset = 0
limit = 20

while True:
    response = sdk.projects.list(limit=limit, offset=offset)
    
    if not response['data']:
        break
        
    for project in response['data']:
        print(f"プロジェクト: {project['name']}")
    
    offset += limit

フィルタリングとソート

// JavaScript
const projects = await sdk.projects.list({
  filter: {
    status: 'active',
    created_after: '2024-01-01',
    tags: ['web', 'mobile']
  },
  sort: {
    field: 'created_at',
    direction: 'desc'
  },
  limit: 50
});

# Python
projects = sdk.projects.list(
    filter={
        'status': 'active',
        'created_after': '2024-01-01',
        'tags': ['web', 'mobile']
    },
    sort={
        'field': 'created_at',
        'direction': 'desc'
    },
    limit=50
)

バッチ操作

JavaScript/TypeScript

// バッチでユーザー作成
const users = await sdk.users.createBatch([
  { email: 'user1@example.com', name: 'User 1' },
  { email: 'user2@example.com', name: 'User 2' },
  { email: 'user3@example.com', name: 'User 3' }
]);

// バッチで更新
const updatedProjects = await sdk.projects.updateBatch([
  { id: '1', name: 'Updated Project 1' },
  { id: '2', name: 'Updated Project 2' }
]);

// バッチで削除
await sdk.users.deleteBatch(['user-id-1', 'user-id-2', 'user-id-3']);

ファイル操作

アップロード

// JavaScript - 単一ファイル
const file = await sdk.files.upload({
  file: fileBuffer,
  filename: 'document.pdf',
  contentType: 'application/pdf',
  metadata: {
    description: 'Important document',
    tags: ['contract', 'legal']
  }
});

// 複数ファイル
const files = await sdk.files.uploadBatch([
  { file: file1Buffer, filename: 'doc1.pdf' },
  { file: file2Buffer, filename: 'doc2.pdf' }
]);

ダウンロード

// JavaScript
const fileData = await sdk.files.download('file-id');
const blob = new Blob([fileData], { type: 'application/pdf' });

// ストリーミングダウンロード
const stream = await sdk.files.downloadStream('file-id');

# Python
# ファイルダウンロード
file_data = sdk.files.download('file-id')
with open('downloaded_file.pdf', 'wb') as f:
    f.write(file_data)

# ストリーミングダウンロード
with sdk.files.download_stream('file-id') as stream:
    with open('large_file.pdf', 'wb') as f:
        for chunk in stream:
            f.write(chunk)

Webhook

JavaScript/TypeScript

// Webhookの設定
const webhook = await sdk.webhooks.create({
  url: 'https://your-app.com/webhooks',
  events: ['user.created', 'project.updated'],
  secret: 'webhook-secret'
});

// Webhookの検証
import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === `sha256=${expectedSignature}`;
}

// Express.jsでの使用例
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-yourapp-signature'] as string;
  const payload = req.body.toString();
  
  if (!verifyWebhook(payload, signature, 'webhook-secret')) {
    return res.status(401).send('Unauthorized');
  }
  
  const event = JSON.parse(payload);
  console.log('Webhookイベント受信:', event.type);
  
  res.status(200).send('OK');
});

リアルタイム通信

WebSocket

// JavaScript
const ws = sdk.realtime.connect({
  channels: ['project.123', 'user.456']
});

ws.on('connect', () => {
  console.log('WebSocket接続が確立されました');
});

ws.on('message', (data) => {
  console.log('リアルタイムメッセージ:', data);
});

ws.on('project.updated', (project) => {
  console.log('プロジェクトが更新されました:', project);
});

// メッセージ送信
ws.send('project.123', {
  type: 'status_update',
  status: 'in_progress'
});

Server-Sent Events (SSE)

// JavaScript
const eventSource = sdk.realtime.createEventSource({
  channels: ['notifications']
});

eventSource.addEventListener('notification', (event) => {
  const notification = JSON.parse(event.data);
  console.log('新しい通知:', notification);
});

eventSource.addEventListener('error', (error) => {
  console.error('SSEエラー:', error);
});

設定オプション

共通設定

// JavaScript
const sdk = new YourAppSDK({
  // 必須設定
  apiKey: 'your-api-key',
  
  // 環境設定
  environment: 'production', // 'sandbox', 'staging', 'production'
  baseUrl: 'https://api.yourapp.com', // カスタムベースURL
  
  // タイムアウト設定
  timeout: 30000, // ミリ秒
  retryTimeout: 5000,
  
  // リトライ設定
  maxRetries: 3,
  retryDelay: 1000,
  retryDelayMultiplier: 2,
  
  // ログ設定
  debug: false,
  logLevel: 'info', // 'debug', 'info', 'warn', 'error'
  
  // レート制限
  rateLimit: {
    enabled: true,
    maxRequests: 100,
    windowMs: 60000 // 1分
  },
  
  // キャッシュ設定
  cache: {
    enabled: true,
    ttl: 300000, // 5分
    maxSize: 100
  }
});

環境変数

# .env ファイル
YOURAPP_API_KEY=your-api-key
YOURAPP_ENVIRONMENT=production
YOURAPP_BASE_URL=https://api.yourapp.com
YOURAPP_TIMEOUT=30000
YOURAPP_DEBUG=false

// JavaScript - 環境変数からの自動読み込み
const sdk = new YourAppSDK(); // 環境変数から自動設定

テスト

モック

JavaScript/TypeScript

import { YourAppSDK } from '@yourapp/sdk';
import { MockYourAppSDK } from '@yourapp/sdk/testing';

// テスト用のモックSDK
const mockSdk = new MockYourAppSDK();

// モックレスポンスの設定
mockSdk.users.create.mockResolvedValue({
  id: 'user-123',
  email: 'test@example.com',
  name: 'Test User'
});

// テスト実行
const user = await mockSdk.users.create({
  email: 'test@example.com',
  name: 'Test User'
});

expect(user.id).toBe('user-123');
expect(mockSdk.users.create).toHaveBeenCalledWith({
  email: 'test@example.com',
  name: 'Test User'
});

Python

from unittest.mock import Mock, patch
from yourapp_sdk import YourAppSDK

# モックSDKの作成
mock_sdk = Mock(spec=YourAppSDK)
mock_sdk.users.create.return_value = {
    'id': 'user-123',
    'email': 'test@example.com',
    'name': 'Test User'
}

# テスト実行
user = mock_sdk.users.create({
    'email': 'test@example.com',
    'name': 'Test User'
})

assert user['id'] == 'user-123'
mock_sdk.users.create.assert_called_once_with({
    'email': 'test@example.com',
    'name': 'Test User'
})

統合テスト

// JavaScript - Jest
describe('YourApp SDK Integration Tests', () => {
  let sdk;
  
  beforeAll(() => {
    sdk = new YourAppSDK({
      apiKey: process.env.TEST_API_KEY,
      environment: 'sandbox'
    });
  });
  
  test('should create and retrieve user', async () => {
    // ユーザー作成
    const createdUser = await sdk.users.create({
      email: 'integration-test@example.com',
      name: 'Integration Test User'
    });
    
    expect(createdUser.id).toBeDefined();
    expect(createdUser.email).toBe('integration-test@example.com');
    
    // ユーザー取得
    const retrievedUser = await sdk.users.get(createdUser.id);
    expect(retrievedUser.id).toBe(createdUser.id);
    expect(retrievedUser.email).toBe(createdUser.email);
    
    // クリーンアップ
    await sdk.users.delete(createdUser.id);
  });
});

パフォーマンス最適化

接続プーリング

// JavaScript
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  connectionPool: {
    maxConnections: 10,
    keepAlive: true,
    keepAliveMsecs: 30000
  }
});

バッチ処理

// JavaScript - 効率的なバッチ処理
const batchSize = 100;
const allUsers = [];

for (let i = 0; i < userDataArray.length; i += batchSize) {
  const batch = userDataArray.slice(i, i + batchSize);
  const createdUsers = await sdk.users.createBatch(batch);
  allUsers.push(...createdUsers);
  
  // レート制限を避けるための待機
  if (i + batchSize < userDataArray.length) {
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

キャッシュ戦略

// JavaScript
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  cache: {
    enabled: true,
    strategy: 'lru', // 'lru', 'fifo', 'ttl'
    maxSize: 1000,
    ttl: 300000, // 5分
    
    // カスタムキャッシュキー生成
    keyGenerator: (method, params) => {
      return `${method}:${JSON.stringify(params)}`;
    }
  }
});

// 手動キャッシュ制御
await sdk.cache.set('user:123', userData, 600000); // 10分
const cachedUser = await sdk.cache.get('user:123');
await sdk.cache.delete('user:123');
await sdk.cache.clear(); // 全キャッシュクリア

トラブルシューティング

よくある問題

1. 認証エラー

// 問題: 401 Unauthorized
// 解決策: APIキーの確認
const sdk = new YourAppSDK({
  apiKey: process.env.YOURAPP_API_KEY, // 正しいAPIキーを設定
  environment: 'production' // 正しい環境を指定
});

2. レート制限

// 問題: 429 Too Many Requests
// 解決策: リトライ機能の実装
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  maxRetries: 5,
  retryDelay: 2000,
  retryDelayMultiplier: 2
});

3. タイムアウトエラー

// 問題: Request timeout
// 解決策: タイムアウト値の調整
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  timeout: 60000, // 60秒に延長
  retryTimeout: 10000
});

デバッグ

// JavaScript - デバッグモードの有効化
const sdk = new YourAppSDK({
  apiKey: 'your-api-key',
  debug: true,
  logLevel: 'debug'
});

// カスタムロガーの設定
sdk.setLogger({
  debug: (message, data) => console.log('[DEBUG]', message, data),
  info: (message, data) => console.log('[INFO]', message, data),
  warn: (message, data) => console.warn('[WARN]', message, data),
  error: (message, data) => console.error('[ERROR]', message, data)
});

ログ分析

// JavaScript - リクエスト/レスポンスのログ
sdk.on('request', (config) => {
  console.log('リクエスト送信:', {
    method: config.method,
    url: config.url,
    headers: config.headers
  });
});

sdk.on('response', (response) => {
  console.log('レスポンス受信:', {
    status: response.status,
    headers: response.headers,
    duration: response.duration
  });
});

sdk.on('error', (error) => {
  console.error('エラー発生:', {
    message: error.message,
    code: error.code,
    request: error.config
  });
});

ベストプラクティス

1. エラーハンドリング

// 包括的なエラーハンドリング
async function createUserSafely(userData) {
  try {
    const user = await sdk.users.create(userData);
    return { success: true, data: user };
  } catch (error) {
    if (error instanceof ValidationError) {
      return { 
        success: false, 
        error: 'validation', 
        details: error.details 
      };
    } else if (error instanceof NetworkError) {
      return { 
        success: false, 
        error: 'network', 
        message: 'ネットワーク接続を確認してください' 
      };
    } else {
      return { 
        success: false, 
        error: 'unknown', 
        message: error.message 
      };
    }
  }
}

2. リソース管理

// 適切なリソース管理
class UserManager {
  constructor() {
    this.sdk = new YourAppSDK({
      apiKey: process.env.YOURAPP_API_KEY
    });
  }
  
  async cleanup() {
    // WebSocket接続のクリーンアップ
    if (this.sdk.realtime) {
      await this.sdk.realtime.disconnect();
    }
    
    // キャッシュのクリア
    await this.sdk.cache.clear();
  }
}

// プロセス終了時のクリーンアップ
process.on('SIGINT', async () => {
  await userManager.cleanup();
  process.exit(0);
});

3. セキュリティ

// セキュアな設定
const sdk = new YourAppSDK({
  apiKey: process.env.YOURAPP_API_KEY, // 環境変数から読み込み
  
  // HTTPS強制
  secure: true,
  
  // リクエスト署名
  signRequests: true,
  
  // センシティブデータのログ除外
  logSensitiveData: false
});

// APIキーの検証
if (!process.env.YOURAPP_API_KEY) {
  throw new Error('YOURAPP_API_KEY環境変数が設定されていません');
}

サポートとリソース

ドキュメント

• API リファレンス
• 認証ガイド
• Webhook ガイド

コミュニティ

• GitHub リポジトリ
• Discord コミュニティ
• Stack Overflow

サポート

• サポートチケット
• FAQ
• メール: sdk-support@yourapp.com

更新情報

• 変更ログ
• マイグレーションガイド
• リリースノート