API仕様

外部システム向けのREST APIです。このページでは一覧取得と登録を説明します。 画面の更新・削除操作に対応するAPIは未定義です。

エンドポイント一覧

エンドポイントは、APIの呼び出し先です。メソッドとパスの組み合わせで操作を指定します。

メソッド	パス	用途	詳細
GET	/api/v1/tasks	タスクの一覧取得	一覧取得
POST	/api/v1/tasks	タスクの登録	登録

共通の認証

リクエストの X-API-Key ヘッダーにAPIキーを指定します。 APIのホスト名、キーの発行方法・権限、認証失敗時の応答は未定義です。

以下のHTTP例のホストとキーは説明用の仮値です。このサイトのURLへ送信してもAPIは動きません。

タスク一覧取得

リクエスト例

担当者IDが10のタスクを、1ページあたり20件で取得する例です。

GET /api/v1/tasks?assignee_id=10&page=1&per_page=20 HTTP/1.1
Host: api.example.com
X-API-Key: YOUR_API_KEY

クエリ

クエリは、URLの ? 以降で指定する条件です。

名前	型	意味・制約	要確認事項
status	string	未着手 / 進行中 / 完了で絞り込み	省略時の対象範囲
assignee_id	number	担当者IDで絞り込み	存在しないIDを指定した場合
page	number	ページ番号。1始まり	省略時の値・範囲外の場合
per_page	number	1ページあたりの件数。最大100	既定値・最小値・上限超過時の応答

レスポンス例

{
  "tasks": [
    {
      "id": 1,
      "title": "仕様書レビュー",
      "assignee_id": 10,
      "due_date": "2026-02-15",
      "status": "進行中",
      "priority": "高"
    }
  ],
  "total": 1
}

フィールド	型	意味
tasks	array	このページのタスクの配列
tasks[].id	number	タスクID
tasks[].title	string	タイトル
tasks[].assignee_id	number	担当者ID
tasks[].due_date	string	期限。例は YYYY-MM-DD 形式
tasks[].status	string	未着手 / 進行中 / 完了
tasks[].priority	string	高 / 中 / 低
total	number	総件数。フィルタ前後のどちらを指すかは要確認

期限未設定時の返却形式と、一覧取得成功時のHTTPステータスは未定義です。

タスク登録

登録の流れ

sequenceDiagram
    autonumber
    participant Client as 外部システム
    participant API as タスクAPI
    Client->>API: POST /api/v1/tasks
    API->>API: 入力内容を検証
    alt 登録成功
        API-->>Client: 201 Created
    else 入力内容に問題がある
        API-->>Client: 422 入力エラー
    end

図は登録に成功した場合と、入力内容に問題がある場合の応答を示しています。 認証失敗や通信失敗の応答は、このサンプルでは未定義です。

リクエスト例

POST /api/v1/tasks HTTP/1.1
Host: api.example.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "仕様書レビュー",
  "assignee_id": 10,
  "due_date": "2026-02-15",
  "priority": "高"
}

リクエストボディ

リクエストボディには、登録するデータをJSONで記載します。

名前	型	必須	制約・既定値	画面の項目
title	string	必須	最大100文字	タイトル
assignee_id	number	必須	担当者のユーザーID	担当者
due_date	string	任意	YYYY-MM-DD	期限
priority	string	任意	高 / 中 / 低。省略時は中	優先度

ステータスは登録リクエストの定義に含まれていません。登録時の初期値は要確認です。

レスポンス

結果	HTTPステータス	ボディ
登録成功	201 Created	登録したタスクオブジェクト
入力内容に問題がある	422 Unprocessable Entity	エラーの形式は未定義

実装前に決めること

論点	決める内容
認証・権限	APIキーの発行・失効、操作範囲、認証失敗時の応答
入力とエラー	不正な日付、存在しない担当者、エラーボディの形式
任意項目	期限省略時の保存・返却形式。null を受け付けるか
一覧	ページの既定値、総件数の意味、検索・ソート条件
登録	初期ステータス、成功レスポンスの全フィールド
更新・削除	公開APIに含めるか。含める場合は操作と応答

機能一覧と照らし合わせ、画面とAPIで同じ項目・制約を扱っているか確認してください。