REST API の基礎
REST API とは
REST（Representational State Transfer）API は、HTTP プロトコルを利用してシステム間でデータをやり取りするための設計スタイルである。REST は 2000 年に Roy Fielding の博士論文で提唱されたアーキテクチャスタイルであり、Web の仕組みを活用してシンプルで拡張性の高い API を設計できる。
REST API では、データやリソースを URL で表現し、HTTP メソッド（GET / POST / PUT / DELETE）で操作する。レスポンスのデータ形式としては JSON が現在の主流である。
なぜ SIer で重要か
SIer の業務システムは、単独で完結するシステムは少なく、複数のシステムが連携して業務を実現することが一般的である。かつてはシステム間連携に SOAP や独自プロトコル、ファイル連携が多く使われていたが、近年は REST API による連携が急速に増えている。
その背景には以下がある。
- マイクロサービスの普及 --- システムを小さなサービスに分割し、REST API で連携する設計が増えている
- クラウドサービスの利用 --- AWS、Azure 等のクラウドサービスは REST API を提供しており、業務システムからの呼び出しが必要
- モバイル対応 --- スマートフォンアプリのバックエンドとして REST API を提供するケースが増加
- 外部連携の増加 --- 他社システムや SaaS との連携に REST API が使われる
REST API の基礎を理解しておくことは、設計書の「IF（インターフェース）設計」を読み書きする上で必須となっている。
基本概念
リソースと URL
REST API では、操作対象のデータを「リソース」と呼び、URL（URI）で一意に識別する。
https://api.example.com/users ← ユーザー一覧（コレクション）
https://api.example.com/users/123 ← ID:123 のユーザー（個別リソース）
https://api.example.com/users/123/orders ← ID:123 のユーザーの注文一覧
URL は名詞で表現し、動詞（getUser、deleteOrder 等）は使わないのが REST の原則である。
HTTP メソッド
リソースに対する操作は HTTP メソッドで表現する。
| HTTP メソッド | 操作 | 説明 | 例 |
|---|---|---|---|
| GET | 取得（Read） | リソースの取得。データを変更しない | GET /users/123 |
| POST | 作成（Create） | 新しいリソースの作成 | POST /users |
| PUT | 更新（Update） | リソースの全体を更新 | PUT /users/123 |
| DELETE | 削除（Delete） | リソースの削除 | DELETE /users/123 |
この 4 つの操作はデータベースの CRUD（Create / Read / Update / Delete）に対応している。
HTTP ステータスコード
API のレスポンスには HTTP ステータスコードが含まれ、処理結果を示す。
| コード | 意味 | 使用例 |
|---|---|---|
| 200 | OK | 正常に取得・更新できた |
| 201 | Created | 新しいリソースが作成された |
| 400 | Bad Request | リクエストの形式が不正 |
| 401 | Unauthorized | 認証が必要 |
| 404 | Not Found | リソースが見つからない |
| 500 | Internal Server Error | サーバー側のエラー |
JSON 形式
REST API のリクエスト・レスポンスのデータ形式としては JSON（JavaScript Object Notation） が主流である。
{
"id": 123,
"name": "田中太郎",
"email": "tanaka@example.com",
"department": "営業部",
"createdAt": "2026-03-24T10:00:00Z"
}
JSON はテキストベースで人間にも読みやすく、ほぼすべてのプログラミング言語でパースできるため、システム間連携のデータ形式として広く普及している。
SIer での使われ方
IF 設計書（インターフェース設計書）
SIer のプロジェクトでは、REST API の仕様は IF 設計書（インターフェース設計書） として文書化される。IF 設計書には以下の項目が記載される。
- エンドポイント URL
- HTTP メソッド
- リクエストパラメータ・リクエストボディの定義
- レスポンスボディの定義
- HTTP ステータスコードとエラーレスポンスの定義
- 認証・認可の方式
近年は OpenAPI（Swagger） 仕様で API 定義を記述するプロジェクトも増えている。OpenAPI 仕様から API ドキュメントやクライアントコードを自動生成できるため、開発効率の向上に寄与している。
SOAP との比較
SIer の現場では、特に官公庁や金融系のレガシーシステムで SOAP（Simple Object Access Protocol） が使われていることがある。
| 観点 | REST | SOAP |
|---|---|---|
| データ形式 | JSON（XML も可） | XML のみ |
| プロトコル | HTTP | HTTP, SMTP 等 |
| 仕様の厳密さ | 緩い（設計ガイドラインベース） | 厳密（WSDL で定義） |
| 学習コスト | 低い | 高い |
| 普及度（新規開発） | 主流 | 減少傾向 |
新規開発では REST API が主流だが、既存システムとの連携では SOAP を使わざるを得ないケースも残っている。
認証方式
REST API のセキュリティとして、SIer の現場では以下の認証方式がよく使われる。
- API キー --- リクエストヘッダーにキーを付与する最もシンプルな方式
- Bearer トークン（JWT） --- ログイン後に取得したトークンをリクエストヘッダーに付与する方式
- OAuth 2.0 --- 外部サービス連携で使われる認可フレームワーク
まとめ
- REST API は HTTP プロトコルを利用してリソースを操作する設計スタイルである
- GET / POST / PUT / DELETE の HTTP メソッドで CRUD 操作を表現する
- データ形式は JSON が主流であり、URL でリソースを一意に識別する
- SIer でもシステム間連携・クラウド連携・モバイル対応で REST API の利用が増加している
- IF 設計書として仕様が文書化され、OpenAPI による仕様管理も普及しつつある