The REST APIs and HATEOAS

HATEOAS, an acronym for Hypermedia As The Engine Of Application State, is a constraint of the REST application architecture.

Each PayPal API call response includes an array of contextual HATEOAS links, if available. Use these links to request more information about and construct an API flow that is relative to a specific request.

HATEOAS example

This excerpt from a sample response shows an example of HATEOAS links:

{  
  "links": [{
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
    "rel": "refund",
    "method": "POST"
  }, {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
    "rel": "parent_payment",
    "method": "GET"
  }]
}

The response contains an array of HATEOAS links. In this example, you can use these links, as follows:

  • Use the self link to get more information about the request. Combine the method and the target URL to make the call:
    GET https://api.paypal.com/v1/payments/sale/36C38912MN9658832
    
  • Use the refund link to request a refund:
    POST https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund
    
  • Use the parent_payment link to get information about the parent payment:
    GET https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI
    

The next topic describes the elements in each link object.

Each link object in the array of HATEOAS links includes:

Element Required Description
href Required The target URL.
rel Required The link relationship type.
method Optional The HTTP method. Default is GET.

The href element

The href element contains the complete target URL, or link, to use in combination with the HTTP method to make the related call. href is the key HATEOAS component that links a completed call with a subsequent call.

The rel element

The rel element contains the link relationship type, or how the href link relates to the previous call.

The link relationship types are:

Relationship Use this link to
approval_url Direct the user to this location on the PayPal site so that he or she can approve the payment.
authorization Show authorized payment details for a captured payment.
cancel Cancel a subscription.
capture Capture an authorized payment.
collection Access a collection.
confirm Confirm an account.
create Create a resource.
delete Delete a resource.
execute Execute an approved PayPal payment.
first Navigate to the first page of the result list.
last Navigate to the last page of the result list provided total_required is specified as a query parameter.
mark-as-paid Mark a request as paid.
next Navigate to the next page of the result list.
order Show order details.
parent_payment Get information about the original payment. All payment-related calls, including payments, sales, refunds, authorizations, captures, and orders, have a parent payment.
patch Update a stored credit card.
pay Pay a request.
prev Navigate to the previous page of the result list.
previous Navigate to the previous page of the result list.
re_activate Reactivate a billing agreement.
reauthorize Reauthorize an authorized PayPal payment.
refund Refund a sale.
remind Send a reminder about a request.
replace Completely update, or replace, a resource.
resend Resend a webhook event.
sale Show sale details.
self Get information about the call itself. Use the self link returned by a PayPal payment request to get more information about the payment. Or, use the self link returned by a refund request to get more information about the refund.
send Send an invoice.
suspend Suspend a billing agreement.
up Navigate to the parent resource in a hierarchy of resources.
update Edit or partially update a resource.
void Void an authorized payment.

The method element

Optional. The method element contains an HTTP method. If present, use this method to make a request to the target URL. If absent, the default method is GET.

The HTTP methods are:

Method Description
DELETE Deletes a resource.
GET Shows details for a resource or lists resources.
PATCH Partially updates a resource.
POST Creates or manages a resource.
PUT Updates a resource.
REDIRECT Not an HTTP method but specifies that the target URL is a redirect URL to which to redirect payers to approve a PayPal account payment.

Additional information