Intra-mart Web API MakerでREST APIを作成する方法（認証込み完全ガイド）
Intra-mart Accel Platformでは「Web API Maker」を使うことで、JavaアノテーションベースでREST APIを簡単に作成できます。
ただし実務では「API作成」だけでなく、「認証方式の選択」まで含めて設計する必要があります。
本記事では以下をまとめて解説します：
- Web API Makerの全体構造
- REST APIの作成手順
- 認証アノテーション3種類
- 実務での使い分け
1. Web API Makerとは
Web API Makerは、Javaクラスにアノテーションを付与することでREST APIとして公開できる仕組みです。
特徴
- Javaコード＝APIになる
- URL・HTTPメソッドをアノテーションで定義
- JSON自動変換
- API仕様の自動生成
2. API作成の全体フロー
Web APIの作成は以下のステップで行います。
STEP 1：ファクトリクラス作成
サービスクラスの生成元を定義します。
@ProvideService
役割：
- DIコンテナ的な役割
- サービスインスタンス生成
STEP 2：サービスクラス作成（API本体）
ここがREST APIの中心です。
2.1 エンドポイント定義
@Path("/user")
public class UserService {
2.2 HTTPメソッド定義
| メソッド | 用途 |
|---|---|
| @GET | 取得 |
| @POST | 作成 |
| @PUT | 更新 |
| @DELETE | 削除 |
2.3 API実装例
@GET
@Path("/{id}")
public User getUser(@Variable("id") String id) {
return userService.findById(id);
}
2.4 JSON受け取り
@POST
public void createUser(@Body User user) {
userService.insert(user);
}
STEP 3：パッケージ登録
作成したクラスをWeb APIとして公開します。
3. パラメータの受け取り方法
| アノテーション | 内容 |
|---|---|
| @Variable | URLパス |
| @Parameter | クエリパラメータ |
| @Header | HTTPヘッダ |
| @Body | JSONボディ |
4. Web APIの認証（重要）
Web API Makerでは認証方式をアノテーションで切り替えます。
認証は大きく3種類あります。
① @IMAuthentication（セッション認証）
概要
Intra-martログインセッション（Cookie）を使う認証方式。
@IMAuthentication
@Path("/user")
public class UserService {
特徴
- 社内Webアプリ向け
- Cookieベース認証
- Intra-martログインと連動
メリット
- 実装が簡単
- 権限管理と連携可能
デメリット
- 外部APIに不向き
- セッション依存
② @BasicAuthentication（Basic認証）
概要
HTTP Basic認証を利用する方式。
@BasicAuthentication
@Path("/user")
public class UserService {
URL構造
/basic + @Pathの値
例：
/basic/user
特徴
- 外部連携向け
- シンプル構成
- 毎回認証情報を送信
メリット
- 実装が軽い
- Postmanでテストしやすい
デメリット
- HTTPS必須
- セキュリティは弱め
③ @OAuth（トークン認証）
概要
アクセストークンを利用した認証方式。
@OAuth
@Path("/user")
public class UserService {
仕組み
Authorization: Bearer xxxxx
特徴
- 外部API・モバイル向け
- ステートレス
- スコープ管理可能
メリット
- 高セキュリティ
- 外部連携に最適
デメリット
- 実装が複雑
- トークン管理が必要
5. 認証3種類の関係
実務ではこう整理する：
① @IMAuthentication（ログイン）
↓
② @Authz（権限チェック）
↓
③ @Secured（リクエスト保護）
※ Basic / OAuthは用途別に置き換え
6. 実務での使い分け
社内業務API
@IMAuthentication + @Authz
- 社員向けシステム
- Intra-martログイン前提
外部連携API（簡易）
@BasicAuthentication
- テスト環境
- 軽量連携
本番外部API
@OAuth
- Salesforce連携
- モバイルアプリ
- マイクロサービス
7. よくあるエラー
401 Unauthorized
- 認証失敗
- セッション切れ
403 Forbidden
- 権限不足（@Authz）
- トークン不正
500 Internal Error
- JSON変換エラー
- Null処理ミス
8. まとめ
Intra-mart Web API Makerは単なるREST生成ツールではなく、
👉 「認証・認可込みの業務APIフレームワーク」
です。
重要ポイント
APIはJava＋アノテーションで作成
認証は3種類
- @IMAuthentication（社内）
- @BasicAuthentication（簡易外部）
- @OAuth（外部本番）
実務では用途で使い分ける
最後に
この仕組みの本質はこれです：
👉 「APIを作る」ではなく
👉 「誰にどう使わせるかを設計する」
もし次ステップやるならかなり強い記事👇
- CRUD完全実装サンプル
- Salesforce連携API設計
- IM-Authzロール設計
- OAuthトークン設計の実務パターン
必要なら「コード付き完全サンプルプロジェクト構成」まで落として、シリーズ記事にもできるよ。