Help us understand the problem. What is going on with this article?

PayPal HATEOAS Linkについて

More than 3 years have passed since last update.

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したり、広く参考にされていたりします。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした