📑

【初心者向け】APIとは？使い方と実装方法をわかりやすく解説

2025/03/18に公開1件

APIは現代のソフトウェア開発において非常に重要な要素です。この記事では、APIとは何か、どのように使うのか、そして実際の実装方法について、初心者にもわかりやすく解説します。

APIとは？

API（Application Programming Interface）は、異なるソフトウェアやサービス間でデータをやり取りするための仕組みです。簡単に言えば、「プログラムどうしが会話するための共通言語」です。

APIの役割

データの送受信
- 異なるシステム間でデータを交換
- 必要な情報だけを効率的に取得
機能の提供
- 複雑な処理を簡単に利用可能
- サービスの機能を外部に公開
セキュリティの確保
- アクセス制御
- データの保護

RESTful APIの基本

最も一般的なAPIの形式は「RESTful API」です。

HTTPメソッド

RESTful APIでは、以下の主要なHTTPメソッドを使用します：

GET: データの取得
POST: 新しいデータの作成
PUT/PATCH: 既存データの更新
DELETE: データの削除

エンドポイントの例

GET    /api/users           # ユーザー一覧の取得
GET    /api/users/123      # 特定のユーザーの取得
POST   /api/users          # 新しいユーザーの作成
PUT    /api/users/123      # ユーザー情報の更新
DELETE /api/users/123      # ユーザーの削除

APIの使い方

1. APIリクエストの基本

JavaScriptでのAPIリクエストの例：

// fetch APIを使用した基本的なGETリクエスト
async function getUser(userId) {
  try {
    const response = await fetch(`https://api.example.com/users/${userId}`);
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('エラーが発生しました:', error);
    throw error;
  }
}

// 使用例
getUser(123)
  .then(user => console.log(user))
  .catch(error => console.error(error));

2. データの送信

// POSTリクエストの例
async function createUser(userData) {
  try {
    const response = await fetch('https://api.example.com/users', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(userData)
    });
    
    const data = await response.json();
    return data;
  } catch (error) {
    console.error('エラーが発生しました:', error);
    throw error;
  }
}

// 使用例
const newUser = {
  name: '山田太郎',
  email: 'yamada@example.com',
  age: 25
};

createUser(newUser)
  .then(user => console.log('作成されたユーザー:', user))
  .catch(error => console.error(error));

3. エラーハンドリング

async function fetchData(url) {
  try {
    const response = await fetch(url);
    
    // ステータスコードのチェック
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    const data = await response.json();
    return data;
  } catch (error) {
    // ネットワークエラーやパースエラーの処理
    console.error('データの取得に失敗しました:', error);
    throw error;
  }
}

APIの実装方法

1. Express.jsでのAPI実装例

const express = require('express');
const app = express();

// JSONリクエストの解析
app.use(express.json());

// ユーザーデータ（実際はデータベースを使用）
let users = [
  { id: 1, name: '山田太郎', email: 'yamada@example.com' },
  { id: 2, name: '鈴木花子', email: 'suzuki@example.com' }
];

// ユーザー一覧の取得
app.get('/api/users', (req, res) => {
  res.json(users);
});

// 特定のユーザーの取得
app.get('/api/users/:id', (req, res) => {
  const user = users.find(u => u.id === parseInt(req.params.id));
  
  if (!user) {
    return res.status(404).json({ message: 'ユーザーが見つかりません' });
  }
  
  res.json(user);
});

// 新しいユーザーの作成
app.post('/api/users', (req, res) => {
  const newUser = {
    id: users.length + 1,
    name: req.body.name,
    email: req.body.email
  };
  
  users.push(newUser);
  res.status(201).json(newUser);
});

// サーバーの起動
app.listen(3000, () => {
  console.log('APIサーバーが起動しました（ポート3000）');
});

2. ミドルウェアの活用

// 認証ミドルウェア
function authenticate(req, res, next) {
  const apiKey = req.headers['x-api-key'];
  
  if (!apiKey || apiKey !== 'your-secret-key') {
    return res.status(401).json({ message: '認証が必要です' });
  }
  
  next();
}

// ミドルウェアの適用
app.use('/api', authenticate);

// エラーハンドリングミドルウェア
app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ message: 'サーバーエラーが発生しました' });
});

3. バリデーション

function validateUser(req, res, next) {
  const { name, email } = req.body;
  
  if (!name || name.length < 2) {
    return res.status(400).json({ message: '名前は2文字以上必要です' });
  }
  
  if (!email || !email.includes('@')) {
    return res.status(400).json({ message: '有効なメールアドレスを入力してください' });
  }
  
  next();
}

// バリデーションの適用
app.post('/api/users', validateUser, (req, res) => {
  // ユーザー作成の処理
});

実践的な例：ブログAPIの実装

以下は、簡単なブログシステムのAPIを実装する例です：

const express = require('express');
const app = express();

app.use(express.json());

// ブログ記事データ（実際はデータベースを使用）
let posts = [
  {
    id: 1,
    title: '初めての投稿',
    content: 'これは最初のブログ記事です。',
    author: '山田太郎',
    createdAt: '2024-08-15'
  }
];

// 記事一覧の取得
app.get('/api/posts', (req, res) => {
  // クエリパラメータによるフィルタリング
  const { author } = req.query;
  
  if (author) {
    const filteredPosts = posts.filter(post => post.author === author);
    return res.json(filteredPosts);
  }
  
  res.json(posts);
});

// 特定の記事の取得
app.get('/api/posts/:id', (req, res) => {
  const post = posts.find(p => p.id === parseInt(req.params.id));
  
  if (!post) {
    return res.status(404).json({ message: '記事が見つかりません' });
  }
  
  res.json(post);
});

// 新しい記事の作成
app.post('/api/posts', (req, res) => {
  const { title, content, author } = req.body;
  
  // バリデーション
  if (!title || !content || !author) {
    return res.status(400).json({ message: '必須項目が不足しています' });
  }
  
  const newPost = {
    id: posts.length + 1,
    title,
    content,
    author,
    createdAt: new Date().toISOString().split('T')[0]
  };
  
  posts.push(newPost);
  res.status(201).json(newPost);
});

// 記事の更新
app.put('/api/posts/:id', (req, res) => {
  const postId = parseInt(req.params.id);
  const postIndex = posts.findIndex(p => p.id === postId);
  
  if (postIndex === -1) {
    return res.status(404).json({ message: '記事が見つかりません' });
  }
  
  const { title, content } = req.body;
  
  // 既存の記事を更新
  posts[postIndex] = {
    ...posts[postIndex],
    title: title || posts[postIndex].title,
    content: content || posts[postIndex].content
  };
  
  res.json(posts[postIndex]);
});

// 記事の削除
app.delete('/api/posts/:id', (req, res) => {
  const postId = parseInt(req.params.id);
  const postIndex = posts.findIndex(p => p.id === postId);
  
  if (postIndex === -1) {
    return res.status(404).json({ message: '記事が見つかりません' });
  }
  
  posts.splice(postIndex, 1);
  res.status(204).send();
});

APIのテスト

1. curlを使用したテスト

# GETリクエスト
curl http://localhost:3000/api/posts

# POSTリクエスト
curl -X POST http://localhost:3000/api/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"新しい記事","content":"記事の内容","author":"鈴木花子"}'

# PUTリクエスト
curl -X PUT http://localhost:3000/api/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"title":"更新された記事","content":"新しい内容"}'

# DELETEリクエスト
curl -X DELETE http://localhost:3000/api/posts/1

2. Jest を使用したユニットテスト

const request = require('supertest');
const app = require('./app');

describe('Blog API', () => {
  test('GET /api/posts should return all posts', async () => {
    const response = await request(app).get('/api/posts');
    expect(response.status).toBe(200);
    expect(Array.isArray(response.body)).toBe(true);
  });
  
  test('POST /api/posts should create a new post', async () => {
    const newPost = {
      title: 'テスト記事',
      content: 'テスト内容',
      author: 'テストユーザー'
    };
    
    const response = await request(app)
      .post('/api/posts')
      .send(newPost);
      
    expect(response.status).toBe(201);
    expect(response.body.title).toBe(newPost.title);
  });
});

APIドキュメントの作成

Swagger/OpenAPIを使用した例

openapi: 3.0.0
info:
  title: ブログAPI
  version: 1.0.0
  description: シンプルなブログシステムのAPI

paths:
  /api/posts:
    get:
      summary: 記事一覧の取得
      parameters:
        - in: query
          name: author
          schema:
            type: string
          description: 著者名でフィルタリング
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Post'
    
    post:
      summary: 新しい記事の作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPost'
      responses:
        '201':
          description: 作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'

components:
  schemas:
    Post:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        content:
          type: string
        author:
          type: string
        createdAt:
          type: string
          format: date

セキュリティ対策

1. 認証と認可

const jwt = require('jsonwebtoken');

// JWTを使用した認証
function authenticateToken(req, res, next) {
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1];
  
  if (!token) {
    return res.status(401).json({ message: '認証が必要です' });
  }
  
  jwt.verify(token, process.env.JWT_SECRET, (err, user) => {
    if (err) {
      return res.status(403).json({ message: 'トークンが無効です' });
    }
    
    req.user = user;
    next();
  });
}

// 認証が必要なエンドポイントに適用
app.post('/api/posts', authenticateToken, (req, res) => {
  // 記事作成の処理
});

2. レート制限

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15分
  max: 100 // IPアドレスごとのリクエスト制限
});

// レート制限の適用
app.use('/api', limiter);

3. 入力のサニタイズ

const sanitize = require('sanitize-html');

function sanitizeInput(req, res, next) {
  if (req.body.content) {
    req.body.content = sanitize(req.body.content, {
      allowedTags: [ 'b', 'i', 'em', 'strong', 'a' ],
      allowedAttributes: {
        'a': [ 'href' ]
      }
    });
  }
  next();
}

app.post('/api/posts', sanitizeInput, (req, res) => {
  // 記事作成の処理
});

まとめ

この記事では、APIの基本から実装方法まで幅広く解説しました：

APIの基本概念
- RESTful APIの原則
- HTTPメソッドの使い方
- エンドポイントの設計
実装のポイント
- Express.jsでのAPI実装
- ミドルウェアの活用
- エラーハンドリング
セキュリティ対策
- 認証と認可
- レート制限
- 入力のサニタイズ

APIは現代のWeb開発において非常に重要な要素です。基本をしっかり理解し、セキュリティにも配慮しながら、堅牢なAPIを設計・実装することが大切です。

次のステップ

APIの基本を理解したら、以下の記事も参考にしてください：

Discussion

juner

api というよりも web api の説明でしょうか……？
https://ja.wikipedia.org/wiki/アプリケーションプログラミングインタフェース
例えば ウェブストレージAPI は ブラウザ上の localStorage / sessionStorage を扱う為の API（＝関数・クラス仕様） ですし

https://developer.mozilla.org/ja/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API