HATEOAS and the PayPal REST Payment API

One of the key features of the PayPal REST API is HATEOAS (Hypertext As The Engine Of Application State).

At its core, HATEAOAS provides a way to interact with the REST Payment API entirely through hyperlinks. With each call that you make to the API, we'll return an array of links that allow you to request more information about a call and to further interact with the API. You no longer need to hard code the logic necessary to use the PayPal REST API.

HATEOAS links are contextual, so you only get the information that is relative to a specific request.

Building Blocks of HATEOAS

Let's take a look at a PayPal payment using the REST API. When you send the initial payment request, you'll get back a response that contains a set of HATEOAS links like this:


[
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y",
    "rel":"self",
    "method":"GET"
  },
  {
    "href":"https://www.sandbox.paypal.com/webscr?cmd=_express-checkout&token=EC-60U79048BN7719609",
    "rel":"approval_url",
    "method":"REDIRECT"
  },
  {
    "href":"https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV70583SB702805EKEYSZ6Y/execute",
    "rel":"execute",
    "method":"POST"
  }
]

There are three components for each link in a HATEOAS links array:

  • href: URL of the related HATEOAS link you can use for subsequent calls.
  • rel: Link relation that describes how this link relates to the previous call.
  • method: The HTTP method required for the related call.

href component

The key component within HATEOAS, href provides the linkage between the completed call and a future call. Each href is a fully formed target URL, so you there is no further logic required to access a resource other than the method.

rel component

The rel component provides the relation type for the URL in question.

Here are the possible relation types:

  • self: Link to get information about the call itself. For example, the self link in response to a PayPal account payment provides you with more information about the payment resource itself. Similarly, the self link in the response to a refund will provide you with information about the refund that just completed.

  • parent_payment: Link to get information about the originally created payment resource. All payment related calls (/payments/) through the PayPal REST payment API, including refunds, authorized payments, and captured payments involve a parent payment resource.

  • sale: Link to get information about a completed sale.

  • update: Link to execute and complete user-approved PayPal payments.

  • authorization: Link to look up the original authorized payment for a captured payment.

  • reauthorize: Link to reauthorize a previously authorized PayPal payment.

  • capture: Link to capture authorized but uncaptured payments.

  • void: Link to void an authorized payment.

  • refund: Link to refund a completed sale.

  • delete: Link to delete a credit card from the vault.

method component

The method component provides the HTTP methods required to interact with the provided HATEOAS URL.

Here are the possible methods:

  • POST: Use this method to create or act upon resources, including:

    • create payments
    • refund payments
    • reauthorize payments
    • capture authorized payments
    • void authorized payments
    • store credits cards using the /vault API
  • GET: Use this method to get information about existing resources, including:

    • lists of payment resources
    • completed payments
    • refunds
    • authorizations
    • captured authorizations
    • stored credit cards
  • DELETE: Use this method to remove a resource. Currently, you can use this method to delete stored credit cards.

  • REDIRECT: This method is actually not an HTTP method. It instead provides a redirect URL where payers are redirected to approve a PayPal account payment.