PayPalサブスクリプションの実装でHATEOASと出会った

はじめに

株式会社ウェイブでCoolmicのエンジニアをしている布施です。
Coolmicは日本のコミックを海外向けに配信するWEBサービスです。

PayPalのサブスクリプション機能を実装する中でHATEOASというものを初めて知りました。
調べたことを書きました。

どこで登場する？

プラン変更を実装しているとAPIドキュメントにこのような文言が出てきます。

This type of update requires the buyer's consent.

同意ってどうやって取るんだと思っているとAPIのレスポンスにこんなものがありました。

サブスクリプション作成にも同じようなものがあります。

reviseAPIは次のようなレスポンスを返します。これがHATEOAS Linksらしい。

{
  "plan_id": "P-XXXXXXXX",
  （省略）
  "links": [
    {
      "href": "https://www.paypal.com/webapps/billing/subscriptions/update?ba_token=BA-XXXXXXXX",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-XXXXXXXX",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-XXXXXXXX",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-XXXXXXXX/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    （省略）
  ]
}

HATEOASとは

PayPalのドキュメントはこんな感じです。
linksの各要素を利用して、APIリクエストに対する次の操作を実行することができる、みたいなことが書かれています。

そのリソースに対して、次にできる操作の情報をAPIのレスポンスに含めるようにするフォーマット？のようなものと理解しました。
wikipediaには、アプリとのインタラクションの方法に関する事前知識がほとんどいらなくなる、とありあります。

A REST client needs little to no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.

HATEOAS Linksが与えられている操作は可能で、与えられていない操作は不可能。
リソースの状態によって返されるHATEOAS Linksの組み合わせが変わるので、それをちゃんとパースすれば無理な操作をしてしまうこともなさそうです。

https://en.wikipedia.org/wiki/HATEOAS

PayPalサブスクリプションにおけるHATEOAS

プラン変更機能について、以下のようなユースケースを考えることができます。

• ユーザーがwebアプリ上で変更先のプランを選択すると、reviseリクエストが送られる。
• webアプリは、reviseリクエストのレスポンスからlinksをパースし、次の操作をユーザーに提示する。
  • approve: プラン変更を承認する
  • edit: 請求先などの関連情報の修正を行う
  • cancel: 変更をやめる
• ユーザーの任意の操作に対し、対応したlinkにリクエストが送られる。
• webアプリはレスポンスからlinksをパースし、〇〇の操作をユーザーに提示する。
• ユーザーは...

各リクエストのレスポンスの内容のみでやりとりが完結するので考えることはシンプルになりそうです。

最後に

HATEOASで検索してもあまりヒットしなかったので一般的ではないのかもしれません。
しかし、クライアントの行動を一部制限することで無駄なエラーを減らす、というような考え方は他にも応用できるかもしれないなと思いました。

参考

https://blog.tagbangers.co.jp/ja/2019/04/05/HATEOAS.html

PayPalドキュメント

• Revise plan or quantity of subscription
• Create subscription
• HATEOAS