Design Principles

REST Overview

REST is an architectural style for describing web services. It is not a protocol in an of itself. As a result, the style has general guidelines but each API creator is left to design the API is the most pragmatic way possible.

Guidelines

Most resources follow a RESTful resource pattern:
  • GET requests return objects and won't modify their server instances.
  • POST and DELETE requests will modify their server instances.
  • Resources are defined with plural names.
  • Resource collections are found at the pluralized resource without an identifier. (Example: /cars)
  • An individual resource collection item can be found at the resource with an identifier. (Example: /cars/{id})
  • Performing a GET on a resource collection returns a list of abbreviated items, useful in retrieving any specific item.
  • Performing a POST on a resource collection creates a new item instance, the location of which is returned in the Location header.
  • Performing a GET on a resource item retrieves that specific item. Child properties may return so much data that they are implemented as more specific resources. (Example: cars/{id}/predators)
  • Performing a POST on a resource item will save the instance sent in the request body.
  • Performing a DELETE on a resource item will delete it from the collection.
  • Singular resources belonging to a resource collection item will connote an opertaion on that item instance. The HTTP method used in the request will determine if the operation modifies the instance. GET operations will not affect the intance and will return the result of the operation. POST operations will affect the instance and may not return a result other than a status message.

URL Structure

Example URL: https://api-sandbox.ipaymentinc.com/carinventory/v2/cars/123
Part Name Description Required
https:// Protocol Https is required for all API calls. Yes
api-sandbox.ipaymentinc.com Hostname 'api-sandbox' is used for the sandbox (non-production environment)
'api' is used for the production environment		 Yes
carinventory API Name Yes
v2 API Version Version number (integer) of the API Yes
cars Resource Collection Yes
123 Resource Item ID No

Lookups

Special resources that are available outside of the (RESTful) resource hierarchy are located under the Lookups path. These Lookups will typically consist of value/name pairs that will assit you in building your applications. Some Lookups resource mays be more complex in order to provide a hierarchical relationship between lookups. These Lookups will assist you in building cascading selections in your applications.

Authentication

All Paysafe APIs are stateless and require authentication with every request. Paysafe uses Http Basic Authentication over SSL.
Each call to the API requires an Authorization header with the supplied API key and API secret.


Versioning

API versions follow the pattern v#, starting with v1. Non-breaking contract changes will not necessitate new versions.
New versions will be created when:
  • Functionality is removed
  • Items are removed from existing data structures
  • Substantial functionality is added
  • Substantial data is added to existing data structures possibly resulting in changes to resource usage

Media Types

Data Media Types

The default API data format is JSON.
Be sure to set both the content-type and accept headers for each request as application/json.
XML is also supported by using application/xml.


Document Media Types

The table below describes the media types supported for document uploads
File Type Media Type
PDF application/pdf
TXT text/plain
DOC application/msword
DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document

Dates

All Date objects follow the ISO 8601 standard in the form of yyyy-mm-ddthh:mm:ss.sssz.
Example: 2015-08-31t05:31:54z


HTTP Verbs

The table below describes the various HTTP verbs that can be used in a REST API. For more information see the W3C spec.
Verb Description
GET Retrieves a resource from the API
POST Creates a new item at the specified resource collection
DELETE Removes an item from a resource collection
PUT [Not Implemented]
HEAD [Not Implemented]

HTTP Responses

The table below describes the various HTTP responses that may be returned from the API. For more information see the W3C spec.
Response Code Description Comments
2xx Successful This class of status code indicates that the client's request was successfully received, understood, and accepted.
200 OK The request has succeeded. The information returned with the response is dependent on the method used in the request.
201 Created The request has been fulfilled and resulted in a new resource being created.
3xx Redirection This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request.
4xx Client error The 4xx class of status code is intended for cases in which the client seems to have erred.
400 Bad Request An invalid parameter was passed or the requst object is malformed.
401 Unauthorized You must supply valid API key + secret
403 Forbidden Your API credentials are valid but you do not have access to the resource you are trying to call.
404 Not Found The server has not found anything matching the Request-URI.
406 Not Acceptable An access token is no longer believed to be secure, normally because it was used on a non-HTTPS call. The access token will be invalidated if this error is returned.
413 Request Entity Too Large The server is refusing to process a request because the request entity is larger than the server is willing or able to process.
415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
5xx Server error Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request.
Depending on the error, this could be a transient error (i.e. timeout) where retrying the request will result in a successful call.
All 5xx level errors are logged and analyzed. If the error persists, please contact Paysafe.
500 Internal Server error The server encountered an unexpected condition which prevented it from fulfilling the request.
503 Service Unavailable The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

API Testing

There are a number of ways to test a REST API.

Paysafe provides browsable and executable API documentation based on the Swagger specification.

Postman is a Chrome extension that can be used to test APIs without manually creating URLs.

You may also use a utility like cURL or Fiddler