# Creating, Retrieving, Updating and Deleting resources (CRUD)

Resources are created by making an HTTP POST request to a list endpoint, and updated by PUTting to the detail endpoint of the created resource. Resource data is retrieved using GET and deleted using DELETE, both to the detail endpoint. Making a GET request to a list endpoint that supports it yields a list of URLs to detail endpoints for the resources of that particular resource type. A list endpoint URI is of the following form (host and API version prefix not included):

/my_resource/

A detail endpoint looks like this:

/my_resource/<id>/

where <id> is the ID of the resource residing at this endpoint. In cases where an id field is specified in the input schema for resource creation, the value of <id> will be the id of the created resource. Otherwise the ID is generated by Settle.

A few examples:

https://api.settle.eu/merchant/v1/pos/

is a list endpoint for POSes. This URI:

https://api.settle.eu/merchant/v1/pos/12/

is the detail endpoint for the POS with id 12.

Note that all URLs have a trailing slash by convention.

URIs returned in Location headers are full URLs. The URIs returned by the API in JSON responses are absolute relative URIs, without server hostname. It's up to you to prepend hostname and protocol. A complete URL looks like this:

https://api.settle.eu/merchant/v1/pos/3y987j9o4o23/

In this documentation we'll sometimes leave out the version bit:

/merchant/v1/

when specifying endpoint URLs, for brevity's sake.

# List endpoints

List endpoints are associated with a resource class. Unless otherwise specified, a GET on a list endpoint will return a list of URIs that point to resources of its particular class, together with a cursor called next. The cursor points to the next list endpoint with more resources, and another next cursor. And so on.

GET /merchant/ HTTP/1.1
HOST: server.test
Accept: application/vnd.mcash.api.merchant.v1+json
HTTP/1.1 200 OK
Content-Type: application/vnd.mcash.api.merchant.v1+json

{
    "uris": ["/merchant/abc1/", "/merchant/abc2/", "/merchant/abc3/"],
    "next": "/merchant/?next=asDFgh"
}

# Response status codes

Listed below are the most common http response status codes and what they mean in the Settle API.

200 OK: A successful GET on a list or detail endpoint
201 Created: A successful POST to a detail endpoint, resulting in the creation of a new resource. The response will have a Location header with a URI pointing to the new resource. If Settle identifies a duplicate POST request, which means both the ID chosen by client and data matches that of an earlier request, Settle will not alter the resource but will give the same response with a Location header pointing to the original resource.
204 No content: A successful PUT (update) or DELETE request.
400 Bad request: A malformed request from the client. Typically the schema does not validate for the data supplied in the request body.
404 Not found: The status code for all requests to URLs that do not exist. This also includes detail endpoints that resolve to non-existent resources.
405 Method not allowed: Not all endpoints support the entire set of HTTP methods. This status code is returned if the client attempts to use an HTTP method that is not supported by a particular endpoint.
409 Conflict: A conflicting request by the client. This typically happens when the client tries to create a resource with an ID that already exists, or if it tries to create or update a resource with data that violates a uniqueness constraint on one or more resource fields; generally anytime a resource is being updated in conflicting ways, concurrently.

Certain endpoints might return other status codes than those listed here. Special cases are covered in the Settle API Reference (opens new window).

# Schema definitions

All resources in the Settle API are documented in the Settle API Reference (opens new window), with input and output schemas definitions, with the expected structure of input and output data for the respective API calls. To explain what these schemas mean, let's look at the POS creation (opens new window) method as an example. This method defines the following input schema:

# name

String : required

  • length <= 100
  • Data required (new or existing on update)

Human-readable name of the POS, used for displaying payment request origin to end user.

# type

String : required

  • length <= 50
  • Value in store, webshop, mobile, vending, poster.
  • Data required (new or existing on update).

POS type.

# location

Location (opens new window) : optional : default=null

Merchant location.

# id

String : required

  • length <= 100
  • Data required (new or existing on update)

The ID of the POS that is to be created. Has to be unique for the merchant.

The schema is represented as a two-column table where each row represents a field (i.e. a JSON field) in the data format. For each row the right column contains a descriptive text about the field, contains the field name and lists the various constraints that apply to the field. The first line in the left column contains field name, type (e.g. String), whether the field is optional or required, and the default value for optional fields.

The location field of the example schema has a field type (Location) that is linked to another schema definition-- it is a Complex Type. Complex Types can be single-value types with some special behavior, e.g. the Money (opens new window) type; more commonly they have a nested structure like in this example. Clicking the Location (opens new window) link leads us to the following schema definition.

latitude : Float : optional : default=null Latitude
longitude : Float : optional : default=null Longitude
accuracy : Float : optional : default=null Accuracy in meters.

This means that the location field is a nested structure composed of three other fields-- latitude, longitude and accuracy-- that together represent geographic coordinates. This is best illustrated with an example JSON object that validates for the POS creation input schema:

{
    "id": "POS1",
    "name": "My first POS",
    "type": "store",
    "location": {
        "latitude": 59.0,
        "longitude": 10.0,
        "accuracy": 20.0
    }
}