Format

Welcome to SlimPay’s REST API, the simplest way to onboard your customers online for recurring payments!

Like any REST compliant API, secure communication with SlimPay is done over the Internet via HTTPS. GET, POST or PATCH requests must be sent from you (the client) to SlimPay (the server) using specific static or dynamic URLs and parameters. For dynamic URLs, URL templates are used according to RFC 6570 standards.
Message bodies for POST or PATCH requests must be formatted in JSON. 

POST https://api.preprod.slimpay.com/foo HTTP/1.1
Accept: application/hal+json; profile="https://api.slimpay.net/alps/v1"
Authorization: Basic yourToken
Content-Type: application/json

{
    "someproperty": "somevalue"
}

As you can see from the example above, application/json is used for the content-type header for POST requests.
For PATCH requests, application/merge-patch+json is used.
The Accept header is mandatory for all requests and only application/hal+json is supported, followed by the version of the API you are using in the profile attribute.

HTTP responses from the SlimPay server are in JSON format, with two special properties taken from the HAL specification: _links and _embedded.
All the other properties represent the state of the resource (see example below). 

HTTP/1.1 201 Created
Content-Type: application/hal+json; profile="https://api.slimpay.net/alps/v1"

{
    "someproperty": "somevalue",
    "_links": {
        "self": {
            "href": "https://api.preprod.slimpay.com/foo/4e0ec1bb-a508-11e6-8ec0-000000000000"
        },
        "https://api.slimpay.net/alps#get-bar": {
            "href": "https://api.preprod.slimpay.com/bar/5c1a8b5d-a50d-11e6-8ec0-000000000000"
        }
    },
    "_embedded": {
        "someItemName": [
            {
                "_links": {
                    ...
                },
                "someproperty": "somevalue"
            },
            {
                "_links": {
                    ...
                },
                "someproperty": "somevalue"
            }
        ]
    }
}

The _links special property is a map of key/value pairs, where the key is the relation name (rel) and the value is the corresponding object (or array of objects).
Each link has at least one property, href. This is a URL provided by the SlimPay server where you can send your next HTTP request (see HATEOAS).

In other words, your first request will always be a GET call to the API’s entry point, <server>/. All subsequent URLs will be provided by the server via the _links property.

Looking at the example above, we can make a GET request on the bar resource that is related to the foo resource by following the https://api.slimpay.net/alps#get-bar relation provided by the server. This essentially means doing: 

GET https://api.preprod.slimpay.com/bar/5c1a8b5d-a50d-11e6-8ec0-000000000000 HTTP/1.1
Accept: application/hal+json; profile="https://api.slimpay.net/alps/v1"
Authorization: Basic yourToken

SlimPay links always use a specific relation namespace, (https://api.slimpay.net/alps#), followed by the specific relation being followed (in this case get-bar).
Other links, such as self, are relation names registered with the IANA.

Embedded Resources

The _embedded special property is a map of key/value pairs where the key is the relation name (rel) and the value is the corresponding object (or array of objects). See the example above.
Embedded resources are mainly included to reduce HTTP calls. Related resources may only be partially included, but a GET request on the self link will return its full representation.

The _embedded special property is also used in collections.