Batch: An API to bundle multiple REST operations
REST APIs are vital business tools that allow merchants, partners and developers to consume and build on top of the various payment capabilities that PayPal provides. Whether it is checkout, recurring payments, vaulting or identity operations there are multiple end to end API interactions involved in each of those business flows.
These APIs are also a critical part of the internal Service Oriented Architecture (SOA) at PayPal. Different domains expose various internal capabilities and operations via REST interfaces using which the PayPal platform orchestrates and processes billions of transactions per day.
Earlier this year, Aniket Pol and I started working on a project that would allow for logical bundling of these different REST API operations into one single API call on an as-needed basis. The primary motivation behind this being; cutting down on the number of API calls between external clients (merchants and developers) and PayPal or between different internal services at PayPal.
Reducing multiple API calls into a single API call between client and server allows for enormous performance boost as we cut down significantly on the round trip network time.
Another common business use case is doing bulk API operations. Often large merchants and marketplaces initiate transactions in bulk where they need to create multiple payments at one go.
There was a need for an interface that allows clients to invoke the same API call with different request contexts multiple times via a single optimized API call. This eliminates the need for the clients to call an API endpoint in bulk and write code at their end to manage parallel and sequential requests.
Enter Batch API that facilitates the logical bundling of these multiple REST calls via a simplified interface. This REST API is based on the IETF SCIM specification which provides guidance on how clients can send a large collection of resource operations in a single request. The body of a bulk operation contains a set of HTTP resource operations using one of the HTTP methods supported by the API such as POST, PUT, PATCH, or DELETE.
Using this API one can make both non-dependent and dependent batch requests to the PayPal server.
Non-dependent batch requests do not support dependencies between batch operations.
Non-dependent batch requests contain multiple API operations that are not dependent on each other. For example bulk API operations in which one API endpoint is being called multiple times would be a collection of non-dependent operations.
The PayPal batch server returns the response of the batch request as a single-wrapped response only after receiving responses for individual independent operations.
Here is an example of how a non-dependent batch API request looks like:
Notice how we can define an array of API operations that are independent of each other and send them in one single request. The batch service handles unwrapping them and executing them in an optimized fashion and returns the response.
The response for a batch operation like this also contains an array of operations with individual response metadata and body for each operation.
Dependent batch requests support dependencies between two operations.
Dependent batch requests contain multiple API operations that are dependent on each other. For example, the output of one operation might be passed as input to another operation in the batch request.
Here is an example of how a dependent batch request looks like:
Notice how the dependency is defined. The resource Id generated as part of the first operation (defined by operation Id — f81d4fae-7dec-11d0-a765–00a0c91e6bf6) is used as an input to the second dependent operation in the path as v1/payments/payment/{bulk_id:f81d4fae-7dec-11d0-a765–00a0c91e6bf6}.
The batch service takes care of orchestrating the first request and then using the resource Id generated as the result of that in the second operation. This is exactly how a client consuming 2 dependent APIs sequentially would make the calls as well.
Currently this API is in pilot mode and supports the batching of only certain PayPal Checkout API operations being used by some of our large partners and we plan on making it gradually available for widespread use. We see promising performance gains with these integrations.
Please feel free to drop us a note in case you would be interested in trying out this API for your integration.
Huge shout out to our API architects — Aruna Susarla, Jayadeba Jena; product managers — Adrita Bhor, Rahul Dighe and intern Divya Saxena who helped and guided us on this cross collaborative effort to bring this API to life for our customers.
We’re hiring if you would like to come work on exciting backend platforms and customer facing APIs drop me a DM at @anuragS28.
