iObeya API Facade (v1)

Welcome to the new APIs of iObeya. These documentations provide all the tools you need to manipulate our APIs and extend the power of your iObeya platform. You can also find a wealth of articles and examples on our Resource Center.

If you have any questions or would like more information about using this API for your business, please don't hesitate to contact us at integrations-support@iobeya.com. Our team of experts is available to provide additional guidance and support, and can also offer personalized demonstrations of these powerful tools to help you get the most out of them. We look forward to hearing from you and helping you achieve your business goals with iObeya.

• Getting started
  • Find your API instance URL
  • Set up your authentication
  • Postman Collection and environment variables
  • Perform your first call
• Using the iObeya REST API
• Differences from legacy API

1 - Find your API instance URL

All our online platforms follows the same URL schema: CUSTOMER.iobeya.com where CUSTOMER represents the name that your platform administrator chose at the creation.

Your API endpoint is available at: CUSTOMER.api.iobeya.com where CUSTOMER represents the name of your platform. If your API endpoint is not yet deployed, please contact integrations-support@iobeya.com.

2 - Set up your authentication

Please refer to our authentication documentation. (You will need a platform administrator access)

3 - Postman Collection and environment variables

A Postman collection of requests and its suitable set of environment variables are provided to make some API calls:

• API Facade Collection
• Environment variables

To know how to import collection and environment variables, check the import guide.

In addition, since the OAuth authorization is set onto the Facade directory within the collection, each call in the underlying scripts has to set its Auth policy to inherit from parent.

Please refer to 2 - Set up your authentication for further details on how to set the OAuth dance and retrieve the access token.

4 - Perform your first call

In this section you will learn how to get access to the list of your rooms.

Perform a GET request on the /rooms endpoint:

Curl example:

curl --location --request \ 
GET 'https://CUSTOMER.api.iobeya.com/v1/rooms?page=1&size=10' \
--header 'Authorization: Bearer JWT_TOKEN'

NodeJS example (with axios lib):

const axios = require('axios');

const config = {
  method: 'get',
  url: 'https://CUSTOMER.api.iobeya.com/v1/rooms?page=1&size=10',
  headers: {
    'Authorization': 'Bearer JWT_TOKEN'
  },
  responseType: 'json'
};

axios(config)
.then(function (response) {
  console.log(response.data);
})
.catch(function (error) {
  console.log(error);
});

Replace CUSTOMER by your platform name and JWT_TOKEN by your JWT obtained after following the step 2 of this documentation.

Example of response:

{
  "self": "https://CUSTOMER.api.iobeya.com/v1/rooms?page=1&size=10",
  "kind": "Collection",
  "totalCount": 2,
  "data": [
    {
      "self": "https://CUSTOMER.api.iobeya.com/v1/rooms/e7caefd8-5f55-4247-9762-30dc93cbd467",
      "kind": "Room",
      "id": "e7caefd8-5f55-4247-9762-30dc93cbd467",
      "name": "My room 1"
    },
    {
      "self": "https://CUSTOMER.api.iobeya.com/v1/rooms/5cf09c3d-59a9-4891-927a-3948b522fbca",
      "kind": "Room",
      "id": "5cf09c3d-59a9-4891-927a-3948b522fbca",
      "name": "My demo room"
    }
  ]
}

To access the iObeya API you need to pass a set of authentication credentials with each request.

These credentials are in the form of an OAuth 2.0 access token which represents an iObeya user and allows you to make a request on behalf of that user.

This guide describe how to perform the OAuth 2.0 dance each time by using postman or asking consent of users, if you want to achieve a Machine to Machine (M2M) authentication, please refer to this guide or you can retrieve your personal access token (PAT).

Step one: Register an external application in iObeya

In order to access the iObeya API with an external application, you need to register this application in the iObeya platform beforehand.

From the Administration interface click on Configuration > API and create a new OAuth application.

If you want to use Postman, you can put a fake URI on Redirection URI, and follow the step two below.

After saving the new application in iObeya an identifier will be generated, you will need it as the OAuth client_id of your application.

Step two: Generate access token

You can generate an access token using the authorization code flow with the following endpoints:

• {iobeya-server-url}/s/oauth/authorize
• {iobeya-server-url}/s/oauth/token

Here is an example of token generation using Postman:

1. Create a new Collection on Postman, then click on "Authorization"

• Select OAuth 2.0 for Type
• Select Request headers for Add auth data to

2. Scroll down to the Configure New Token panel

• Select Authorization Code for Grant Type

• Enable Authorize using browser and paste the displayed callback URI (https://oauth.pstmn.io/v1/callback) in the Redirection URI setting of your iObeya external application

• Fill in the URLs, Client ID and Scope settings

• Click on Get New Access Token

3. iObeya will ask you to authenticate and to approve rights delegation

If your browser allows pop-up you should be redirected to Postman with a new access token generated.

Step three: Make a request

You can now use your access token to make requests to the iObeya API by providing it in the request header as a bearer token.

Authorization: Bearer your_access_token

If you used Postman to generate your token, you can click on “Use Token”.

Add a new request on the Collection and make sure to check Inherit auth from parent on the Authorization tab

Postman will automatically use a pre-filled hidden header containing the access token.

In this documentation you learned how to generate an access token for sending your first requests to the iObeya API, please note that some security concerns should be addressed before running some production code.

https://datatracker.ietf.org/doc/draft-ietf-oauth-security-topics/

The main recommendations are:

• Don't use the implicit flow
• Use PKCE for all clients
• Use the state to prevent CSRF attacks (PKCE doesn't replace the state)

The iObeya REST API uses JSON format for request and response body and communicate using the standards HTTP verbs GET POST PUT and DELETE.

A resource can be manipulated using the corresponding HTTP verb and the following URI structure:

https://CUSTOMER.api.iobeya.com/VERSION/RESOURCE-NAME

• CUSTOMER: Please refer to the Find your API instance URL section.
• VERSION: Some endpoints can have multiple versions, please refer to the API reference to find the correct version of the endpoint.
• RESOURCE-NAME: The resource you want to manipulate.

For example, to retrieve the list of all the rooms the following request can be performed: GET https://CUSTOMER.api.iobeya.com/v1/rooms

Responses that may contain large collections are paginated in order to limit the payload size and keep the response time as low as possible.

The page size can be defined by using the size query parameter and the page number using the page query parameter (starting at 1).

A paginated collection will always contain the total count of elements under the totalCount field.

Two optional fields can be present, the next and previous links, allowing to navigate between pages.

If no previous link is present, the current requested page is the first.
if no next link is present, the current requested page is the last.

Example:

{
  "self": "https://CUSTOMER.api.iobeya.com/v1/rooms?page=2&size=2",
  "kind": "Collection",
  "totalCount": 2,
  "previous": "https://CUSTOMER.api.iobeya.com/v1/rooms?page=1,size=2",
  "next": "https://CUSTOMER.api.iobeya.com/v1/rooms?page=3,size=2",
  "data": [
    {
      "self": "https://CUSTOMER.api.iobeya.com/v1/rooms/e7caefd8-5f55-4247-9762-30dc93cbd467",
      "kind": "Room",
      "id": "e7caefd8-5f55-4247-9762-30dc93cbd467",
      "name": "My room 1"
    },
    {
      "self": "https://CUSTOMER.api.iobeya.com/v1/rooms/5cf09c3d-59a9-4891-927a-3948b522fbca",
      "kind": "Room",
      "id": "5cf09c3d-59a9-4891-927a-3948b522fbca",
      "name": "My demo room"
    }
  ]
}

In addition with the HTTP status code, API errors will be returned with a JSON body of application/problem+json media type, following the RFC 7807.

In the response body you will find several fields describing the error:

• status: The HTTP status code.
• title: A short summary of the problem type.
• type: An URI reference that identifies the problem type. This URI is not necessarily resolvable, it's main purpose is to identify the problem type, but it sometimes can give you additional information on the problem. It can also be set to about:blank when the problem has no additional semantics beyond that of the HTTP status code.
• detail: An optional field giving some explanation on the specific occurrence of the problem.

Some additional fields may be present to give more accurate information about the problem encountered.

Example:

{
  "type": "https://iobeya.com/api/guide/validation-error",
  "status": 400,
  "title": "Your request parameters didn't validate",
  "invalidRequest": [
    {
      "message": "A request body is required but none found."
    }
  ]
}

Successful API responses will always contain a kind field representing the type of the object in the response alongside with a self field providing a convenience link to manipulate or request more information on the concerned resource.

Example:

{
  "self": "https://CUSTOMER.api.iobeya.com/v1/rooms/e7caefd8-5f55-4247-9762-30dc93cbd467",
  "kind": "Room",
  "id": "e7caefd8-5f55-4247-9762-30dc93cbd467",
  "name": "My room 1"
}

The iObeya REST API uses the ISO 8601 standard to manipulate dates and times.

You can use any timezone to request the API but the date time in responses will always be set to the UTC timezone to avoid any confusion.

Examples:

• Date: 2021-11-22
• UTC date time: 2021-11-22T10:46:01Z
• UTC+2 date time: 2021-11-22T10:46:01+02:00

• iObeya Legacy API : refers to the iObeya REST API, which is the API that the iObeya client is consuming and QCD REST API.
• iObeya Facade API : refers to the newly developed API designed to simplify the developer experience by providing a modern API hiding the underlying complexity of the iObeya Legacy APIs.

If you want to know more, you can consult our integration guide.

• Legacy API : customer.iobeya.com/s/j OR customer.api.iobeya.com/v0
• Facade API : customer.api.iobeya.com/v1

Using customer.api.iobeya.com/v0 base URI endpoint

We added a /v0 endpoint on customer.api.iobeya.com to make calls to legacy API easier. On this endpoint you can use Bearer JWT header to be authenticated.

In fact when you are performing a call on customer.api.iobeya.com/v0, your call will be automatically redirected to customer.iobeya.com/s/j.

Be careful, the /v0 (legacy) json objects may differ from /v1 (facade) json objects.

The main objective with the new APIs is to simplify the usage for consumers, it relies on using simple JSON on requests and responses.

Example for creating a Standard Card:

• Legacy : POST customer.iobeya.com/s/j/elements
  

{
    "@class": "com.iobeya.dto.BoardCardDTO",
    "@superClass": null,
    "asset": null,
    "assignees": [],
    "boardId": null,
    "boardName": null,
    "checklist": [],
    "collectionDoneCount": 0,
    "collectionSize": 0,
    "color": 16706943,
    "container": {
        "@class": "com.iobeya.dto.EntityReferenceDTO",
        "id": "aad882e8-8d43-471e-985d-dbd0bd4365cb",
        "type": "com.iobeya.dto.ElementContainerDTO"
    },
    "creationDate": 1664193382069,
    "creator": "9ec9dcad-efa3-4918-aa7c-064453aa5b9a",
    "dataItem": null,
    "dataItemDate": null,
    "dataItemIcon": null,
    "dataItemId": null,
    "dataItemName": null,
    "dataItemSourceId": null,
    "dataItemStatus": null,
    "dataItemUrl": null,
    "displayTimestamp": false,
    "entityType": "BoardCard",
    "fontFamily": "arial",
    "height": 197,
    "id": "64B80BE8-3F59-9368-06DA-79A7687BB9D0",
    "isAnchored": false,
    "isArchived": false,
    "isLocked": false,
    "isReadOnly": false,
    "linkLabel": null,
    "linkUrl": null,
    "modificationDate": 1664193384524,
    "modifier": "9ec9dcad-efa3-4918-aa7c-064453aa5b9a",
    "modifierClientId": "596cb103-0504-40d0-9835-7c43d4a18638",
    "name": "Jaune",
    "props": {
        "title": "My Card",
        "description": "",
        "priority": false,
        "metric": "",
        "endDate": null
    },
    "roomName": null,
    "rotationAngle": 0,
    "score": -1,
    "scoreRatio": -1,
    "setName": "Cartes standards",
    "syncInfo": {
        "@class": "com.iobeya.dto.EntityReferenceDTO",
        "id": "6cc2c3ae-3baf-4173-8f4f-418c7c2ec478",
        "type": "com.iobeya.dto.ElementSyncInfoDTO"
    },
    "width": 254,
    "x": 108,
    "y": 1270,
    "zOrder": 124
}

• New API : POST customer.api.iobeya.com/cards
  

{
    "type": "standard",
    "title": "My Card",
    "boardId": "65dd12d0-d317-884a-4f14-08fae11d0dcc",
    "size": "medium"
}

Both endpoints give the same result: a Standard Card is created on a specified board, but from payloads very different.
The first one (the Legacy API one) contains the full required technical iObeya properties whereas the second one (the new API) only contains customer oriented properties.

Manipulate boardId instead of elementContainerId

With the new API, it's no more mandatory to perform additional GET requests to find the elementContainerId of a board (which is a technical object required for iObeya) in order to create elements on it.
You can use directly the boardId property.

Use properties that make sense for consumer

In order to improve the usage of our APIs, the consumer don't need any technical skills specific to iObeya to manipulate objects.
For example, to create a card with a specific size using the Legacy API, the consumer needs to retrieve the different available sizes in pixels (width / height).
Now, the consumer just need to specify the size: small, medium or large property.

We use the simplest and business oriented wording for our JSON inputs/outputs.

Manipulate date and time with ISO format

On Legacy API it's needed to manipulate a timestamp, which is not human-understandable. With the new API, you can use the standard ISO format as it's described on our usage guide.

Related to Assets resources

Related to Boards resources

Related to Cards resources

Related to Domains resources