PayEx Developer Portal - restful-pattern-guideline

REST-full pattern guidance

The resources follows REST-full patterns including hyper-media links, we use hyper-media and backend-for-frontend principles to impose business rules and reduce duplication of business logic. Errors uses HTTP friendly status codes as well as detailed "problem+json" responses.

Route segments

Each resource in the API corresponds to its own route. All routes are structured according to a specific standard, explained below

The below route is an example of a route towards resource3Id, to operate on this resource you must also include the ids of its parentresources in the route.
api.payex.com/ledger/{Subdomain}/v1/{LedgerNumber}/resource1/{resource1Id}/resource2/{resource2Id}/resource3/{resource3Id}

Route segment	Description
Subdomain	which subdomain under "ledger" to call, (customer / invoice / account etc.)
LedgerNumber	The ledger identifier/number at PayEx
resource1Id	Identifier of resource1
resource2Id	identifier of resource2, subresource to resource1
resource3Id	identifier of resource3, subresource to resource2

Basic resources

Basic resources uses the common HTTP patterns for GET, POST, PUT, PATCH, DELETE.

Requests without specific resource identifier - f.ex. /ledger/customer/v1/XXX/customers

HTTP GET - Returns a list of resources
HTTP POST - Creates a new resource

Requests with specific resource identifier - f.ex. /ledger/customer/v1/XXX/customers/1234568

HTTP GET - Returns a specific resource
HTTP PUT - Updates a specific resource
HTTP PATCH - Partially updates a specific resource
HTTP DELETE - Deletes a specific resource

Operation resources

Functions that cannot be mapped directly to resources are called "Operation Resources" they only support HTTP POST.

Requests without specific resource identifier operates on the list

HTTP POST - f.ex. /ledger/customer/v1/XXX/customers/generate-summary - Generates a summary

Requests with specific resource identifier operates on a resource

HTTP POST - f.ex. /ledger/customer/v1/XXX/customers/1234568/initiates-termination - Starts termination of an account

Hyper-media response

The response will include a list of operations that is possible to perform. Below is an example when a HTTP-GET Request is issued to retrieve information on an account. The response includes an "operations" property with a list of possible possible operations. The list of operations returned only contains business-rule and access-control validated operations. In the sample below the only allowed way to interact with the resource is to issue "patch" requests to modify fields. Different states as well as access permissions on the resource affect which operations are returned.

Hyper-media response sample

{
    "@id": "/ledger/customer/v1/501/customers/1234567", //Resource identifier
    //Fields...
    "operations" : [
        {
           "rel" : "partial-update",
           "method" : "patch",
           "href" : "/ledger/customer/v1/501/customers/1234567"
        }
    ]
}

Tip: As an implementing consumer of the api operations should be taken into consideration rather than trying to determine possible operation based on other basic resource properties. By following this tip we: minimize duplication of business logic, simplify maintenance when business rules change, have a clear separation of concerns.

Properties used for idempotency

For operations that are idempotent, clients can make the same call multiple times while giving the same results. In other words, multiple identical requests have the same effect as making a single request.
This can be used to re-run failed requests. For requests that, for example, fail due to timeout, there is a possibility that it has been executed at PayEx. In such cases, the request can be run again without duplicates.
This is based on the same request being sent again. In some cases it is enough that certain references / identifiers are the same, in which case these are marked in the API spec

Ledger and Factoring