PayPalのAPIには、前から使われいてるClassic APIと2年ぐらい前にリリースされた新しいREST APIがあり、REST APIへの機能の移行が徐々に進んでいますが、REST APIの便利な仕様としてHTEOAS Linkがあります。
HATEAOSの説明(Wikipedia)
https://en.wikipedia.org/wiki/HATEOAS
PayPalのHATEOAS Link
https://developer.paypal.com/docs/api/#hateoas-links
HATEOAS, an abbreviation for Hypermedia as the Engine of Application State
ということですが、簡単に言ってしまうとURL(URI)をつかって、APIのデータを表現する方法です。
よく使われるパターンは、
APIが一度に100件しか返さなくて次の100件を取得したい場合に,
https://xxxx.com/search?name=aaa&page=2
みたいなクエリを投げると思いますが、今までは、この「page=2」のクエリ仕様をDeveloperがドキュメントなどを調べて知っておく必要がありました。
これを初めのレスポンス、
https://xxxx.com/search?name=aaa
内に
{next_link : "https://xxxx.com/search?name=aaa&page=2"}
といったように、「次のページを取得するためのURL」というフィールドとして返すことで、
開発者はそのフィールドの値をGETすれば次のデータを取得することができます。
これにより、情報参照の手間が省けるとともに、仮に「page=2」の部分が「offset=101」に仕様変更になったとしても、プログラムの改修をしなくて済むというメリットがあります。
もうひとつのケースとしては、
従業員データを返すAPIなどで、検索結果には
[{emp_id : "001"},
{emp_id : "002"},
{emp_id : "003"}]
というIDが返ってきて、それを詳細データ参照API
https://xxxx.com/detail?id=001
を使ってデータを参照するというケースがあると思いますが、
[{emp_id : "001", rel : "https://xxxx.com/detail?id=001"},
{emp_id : "002", rel : "https://xxxx.com/detail?id=002"},
{emp_id : "003", rel : "https://xxxx.com/detail?id=003"}]
といった参照用のURIを示すことで、データ参照の実装がやりやすくなります。
単発のAPIコールだけでなくて、幾つかのAPIを複合的にコールすることが多いサービスには有効なアプローチかと思います。
決済は、ユーザーアクションや運用に応じた様々なフロー設計が必要なので、このアプローチにはマッチしていると言えます。
PayPalのHATEOASLinkにおいては、支払い関連のAPIで次にコールすべきAPIのエンドポイントや返された支払いデータの詳細を取得するAPIのエンドポイントを、メソッド(POST/GET)とともに指定しています。
(以下はデベロッパーサイトでの例)
"links": [
{
"href": "https://api.sandbox.paypal.com/v1/payments/sale/4RR959492F879224U",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/sale/4RR959492F879224U/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v1/payments/payment/PAY-17S8410768582940NKEE66EQ",
"rel": "parent_payment",
"method": "GET"
}
]
ちなみに、PayPalはこの投稿でも述べたように、APIの標準化にも積極的で、HATEOASで検索すると上記のデベロッパーサイトのページが上位にHITしたり、広く参考にされていたりします。