エンドポイントとバージョニング

API エンドポイントバージョニング URL構造

この記事の対象
レシートローラーAPIを実装する開発者向けです。エンドポイントのURL構造とバージョニングの考え方を説明します。

ベースURL

本番： https://api.receiptroller.io/v1
ステージング： https://api-staging.receiptroller.io/v1

OAuth認可エンドポイントは別ホストです。

認可： https://receiptroller.io/oauth/authorize
トークン： https://receiptroller.io/oauth/token

URL構造

/v{バージョン}/{リソース}[/{ID}][/{サブリソース}]

例：
GET  /v1/receipts                  ← レシート一覧
GET  /v1/receipts/rcp_xyz123       ← 個別レシート
GET  /v1/receipts/rcp_xyz123/items ← レシートの明細
POST /v1/products                  ← 商品作成

バージョニング方針

URLパス方式（/v1/...）を採用。ヘッダー方式は使いません
後方互換性のある変更（フィールド追加など）は同一バージョン内で実施
破壊的変更（フィールド削除・型変更・URL変更）は新バージョン（/v2）として提供
新バージョン公開後、旧バージョンは最低12ヶ月並行稼働

後方互換とみなされる変更

レスポンスへの新フィールド追加
新エンドポイントの追加
任意リクエストパラメータの追加
既存エラーコードに新しいコードを追加

クライアント実装時は未知のフィールドを無視するよう作っておくと、互換性を維持しやすくなります。

破壊的変更の例

既存フィールドの削除・名称変更
フィールドの型変更（string → number 等）
必須リクエストパラメータの追加
認証方式の変更
レート制限の大幅な引き下げ

廃止予告とサポート期間

フェーズ	期間	挙動
通常	―	問題なく動作
廃止予告	廃止12ヶ月前〜	レスポンスに `Sunset` ヘッダー
非推奨	廃止3ヶ月前〜	`Deprecation` ヘッダー追加
廃止	廃止日以降	410 Gone

廃止予告は開発者ポータルの「お知らせ」、メール、Sunsetヘッダーで通知します。

現行バージョンの確認

レスポンスヘッダー X-RR-Api-Version に現在処理したバージョンが含まれます。

HTTP/1.1 200 OK
X-RR-Api-Version: 2026-04-01
Content-Type: application/json