Introduction

The maesn API provides a single API to integrate with a range of systems with similar capabilties. By providing a set of generic reources and standardized operations that are mapped and transformed to the resources and operations of the respective target systems, an integrator can implement a single integration workflow toward the unified API to integrate to all the supported target systems.

Resources are modeled after important concepts in the target systems, such as Accounts, Customers, Invoices, Suppliers, Transactions and others. They are exposed in the API through representations, where each representation provides the most useful way to interact with the resource within a certain use case.

We conform to the HTTP/1.1 protocol as described in the IETF RFCs 7230-7235 unless otherwise stated.

​

Getting started with the API

Follow our quick start guide to started right away.

​

Calling conventions

When calling the API, the client should select a resource and HTTP method matching the expected operation result. The client then sends a request to the API and it replies with the response or returns an error.

The general convention for choosing an HTTP method is:

POST results in the creation of a new resource of a given type.

GET returns the given resource’s representation without any side effects.

PATCH partially or fully changes the state of the given resource.

PUT replaces a given resource or creates (upserts) a new resource if the given resource does not already exist.

DELETE removes or hides a given resource making it inaccessible.

​

Responses

All responses are returned as JSON documents and will contain at least one of the top-level keys:

{
    "meta": {},
    "data": {},
    "errors": {}
}

The keys have the following purposes:

• meta: A meta object that contains non-standard information (pagination, warnings, etc.). Including the meta key is optional.
• data: Contains the actual response information (requested resource representation). The document’s “primary data”.
• errors: An array of error objects.

The keys data and errors will never coexist in the same response.

The primary data is either:

• a single resource object, a single resource identifier object, or null, for requests that target single resources.
• an array of resource objects, an array of resource identifier objects, or an empty array ([]), for requests that target resource collections.

​

Fixed field types

​

Countries

Countries returned by the API are conform to the ISO 3166-1 alpha-2 standard, meaning that all countries are represented by a 2-character code, e.g. DE for Germany.

​

Currencies

All currency codes conform to ISO 4217 (3-letter code).

​

Dates

The dates returned by the API are all represented in UTC (ISO8601 format).

This example 2019-11-14T00:55:31.820Z is defined by the ISO 8601 standard. The T in the middle separates the year-month-day portion from the hour-minute-second portion. The Z on the end means UTC, that is, an offset-from-UTC of zero hours-minutes-seconds. The Z is pronounced “Zulu” per military/aviation tradition.

The format is designed to be easy to parse by machines as well as easy to read by humans across cultures.

​

Feedback

If you have feedback or questions, don’t hesitate to reach out to us via support[at]maesn.com. Access to the API can be requested via the contact form on our website.