API Style Guide
PayPal
API Lifecycle
Updates and VersioningHow to handle API updates and versioning |
Collection Resources
FilteringHow to select some resources in a collection |
PaginationHow to retrieve a range of resources in a collection |
Retrieve a collectionHow to get a collection or resources |
Sorting a collectionHow to sort a collection of resources |
CollectionWhat is a collection (set) of resources |
HTTP Methods
DELETEThe DELETE method deletes the specified resource. |
GETThe GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect. |
PATCHThe PATCH method applies partial modifications to a resource. |
POSTThe POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database. |
PUTThe PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI. |
HTTP methodsGeneral information about HTTP methods usage |
HTTP Protocol
CachingHow to use and provide relevant caching informations |
HTTP StatusesGeneral information about HTTP statuses usage |
HTTP Status Success
200 OKStandard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action. |
204 No ContentThe server successfully processed the request and is not returning any content. |
HTTP Status User Error
400 Bad RequestThe server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing). |
404 Not FoundThe requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. |
422 Unprocessable EntityThe request was well-formed but was unable to be followed due to semantic errors. |
Hypermedia
Hypermedia (read)How to use hypermedia to read data
|
HypermediaHow to use hypermedia
|
Miscellaneous
Query parametersHow to use query parameters |
Performance and bandwidthHow to deal with high traffic or consumers with low bandwith |
Naming
NamingHow to name things
|
Resources
Action resourceHow to use action resource (e.g. resources like /cancel or /approve) |
Create resource with a specific IDHow to create resource with a provided id |
Create resourceHow to create resources |
Delete resourceHow to delete resources |
Batch BulkHow to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce) |
Replace resourceHow to replace (or update fully) a resource |
Retrieve resourceHow to retrieve a resource |
Resource's stateHow to change a resource’s state/status (like processed/sent/paid/…) |
Update resource partiallyHow to udate partially a resource |
Update resourceHow to update a resource |
URL formatHow to design URLs |
ResourceGeneral informations about resources |