API Guidlines (PayPal Standard)

The PayPal platform is a collection of reusable services that encapsulate well-defined business capabilities. Developers are encouraged to access these capabilities through Application Programming Interfaces (APIs) that enable consistent design patterns and principles. This facilitates a great developer experience and the ability to quickly compose complex business processes by combining multiple, complementary capabilities as building blocks.

PayPal APIs follow the RESTful architectural style as much as possible. To support our objectives, we have developed a set of rules, standards, and conventions that apply to the design of RESTful APIs. These have been used to help design and maintain hundreds of APIs and have evolved over several years to meet the needs of a wide variety of use cases.

HTTP Methods

• List Resources
• Use HTTP GET method
• Get an Individual Resource
• Use HTTP GET method
• Create a Resource
• Use HTTP POST method

• Update a resource
• Use HTTP PUT method

• Delete a resource
• Use HTTP DELETE method 
• Patch
• Use HTTP PATCH method 

General

• Names used in APIs should be in correct British english
• Eg : licences instead of license, colour instead of color
• Commonly accepted short forms or abbreviations of long words may use 
• Eg : point of sale as POS
• All dates should be formatted in ISO 8601 standard
• Eg (date): 2019-09-04
• Eg (date and time with timezone) 2019-09-04T05:38:33+00:00
• Eg (date and time with UTC) 2019-09-04T05:38:33Z

API Endpoint Naming 

• URI should be formatted in all lowercase names and MUST be in plural form (If the term doesn't have suitable plural form, such as "evidence", “people” and "weather" the singular form should be used)
• Eg: <base_url>/purchase-requests 

• URLs for Resource Collections
• It is recommended that the URL for a collection of resources be formed from the resource type.

Eg: <base_url>/photos

• URLs for Individual Resources
• Treat collections of resources as sets keyed by resource ID. The URL for an individual resource can be formed by appending the resource’s ID to the collection URL

Eg: <base_url>/<service-name>/photos/1

• Related Resource URLs
• It is recommended that a related resource URL be formed by appending the name of the relationship to the resource’s URL.

Eg: <base_url>/photos/1/comments

• Listing Resources from a Sub Collection
• It is recommended that when listing resources in a sub collection use sub collection alias after main collection
• Eg: GET <base_url>/photos/comments

• Filtering
• It’s recommended that servers that wish to support filtering of a resource collection based upon associations do so by allowing query parameters that combine filter with the association name.

Eg: GET /comments?post=1 HTTP/1.1

Eg: (Multiple Filter values) GET /comments?post=1,2 HTTP/1.1

Eg: (Multiple Filters) GET /comments?post=1,2&author=12 HTTP/1.1

• Sorting
• Server MAY choose to support requests to sort resource collections according to one or more criteria (“sort fields”).

GET /people?sort=age HTTP/1.1

(Multiple by comma seperated) GET /people?sort_by=age|asc,name|desc HTTP/1.1

(Descending with “Minus” - ) GET /articles?sort_by=created|desc,title|asc

• Pagination
• Server MAY choose to limit the number of resources returned in a response to a subset (“page”) of the whole set available.

Eg:GET <base_url>/people?page=&page_size= 

• Custom Methods
• They should only be used for functionality that cannot be easily expressed via standard methods
• A custom method can be associated with a resource, a collection, or a service
• Method should be always POST

Eg:

POST <base_url>/photos/1/comments/1/authorize

POST <base_url>/messages/mark-unread

Response Codes

• Server MUST respond with a 200 OK 

• GET - server MUST respond to a successful request to fetch an individual resource or resource collection.

• Server MUST respond with a 201 Created 
• POST - server MUST respond to a successful request when the requested resources has been created successfully.
• PUT - server MUST respond to a successful request when the requested resources has been updated successfully.

• Server MUST respond with a 204 No Content
• DELETE - server MUST respond to a successful request when the requested resource has been deleted successfully.

• Server MUST return 202 Accepted 
• POST / PUT / DELETE - if a request to create a resource has been accepted for processing, but the processing has not been completed by the time the server responds.

• Server MUST return 403 Forbidden 
• GET / POST / PUT / DELETE - server MUST respond to an unauthorized request.

• Server MUST return 404 Not Found 
• GET / POST / PUT / DELETE - when processing a request that references a related resource that does not exist.

• Server MUST return 409 Conflict 
• POST - when processing a request to create a resource with a client-generated ID that already exists.

• Server Must return 500 Internal Server Error 
• GET / POST / PUT / DELETE- when the server encounters multiple problems for a single request.