Introduction

Introduction

This section is important, please read it carefully as everything that follows is based on it.

Inspiration

Our approach to server-server communication is inspired by Huawei Marketplace's API. However, this API includes additional encryption of subfields (likely to protect against man-in-the-middle attacks). We defend against such attacks by using reputed SSL authorities and ensuring our partners are operating in secure conditions.

Furthermore, we changed some terminology (skip if you have never used Marketplace API)

1. "Instance" is replaced with "First Order" -- to avoid ambiguity with an instance being a virtual machine or a customer tenant
2. We split the first call (createInstance) into two, createCustomer and createFirstOrder

Consumer vs Enterprise

An important distinction needs to be made.

OneOffice is multi-tenant. Each company has a unique instance ID within the database and separated storage location.

If you are also doing a consumer integration it means this: "There is an additional tenant created that is meant for consumers." In other words, you are also an administrator of an existing tenants (adding, removing, resetting users)

Specifics

The call is a GET REST call server-to-server with a bearer token in the header and JSON body.

You need a token from us or your calls will be unceremoniously refused with an appropriate nasty message.

The following example uses command-line cURL which comes with all desktop flavors of Linux -- including MacOS (or is easy to install). If you are unfortunate enough to use Windows for your daily work, you can download many pre-compiled binaries online.

CURL

If you have never used cURL before, this primer is for you.

Request

Below is a sample command line. We set in the environment the values of URL and BEARER.

curl -v \
-X GET $URL \
--header "x-api-key: ${BEARER}" \
--header 'Content-Type: application/json' \
--data '{"method":"createUser", "params":{"email":"test1@oneoffice.bh"}}'

The "slash" at the end of the line is the indicator that another line follows for the same command

Notes

1. Note how all data is passed as JSON. If you are getting errors back about data, test the JSON with a JSON parser online like this one
2. The template for JSON body is {"method":"methodName", "params":"paramsObject"} -- ANYTHING ELSE IS IGNORED
3. FYI: The term "method" means internal function
4. "params" is always a JSON object (i.e. not a primitive like string or number)