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 for enterprise-based API. 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 organization has a unique instance ID within the database and separated storage location.

If you are selling to corporations, where each organization is managing its own users, then you should look at the enterprise page.

If you are selling to users (e.g. email service, drive service etc.) then you have your own instance (with its instance ID) and you need to look at the consumers page.

Technical

The calls are 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. 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)