JSON API

Authentication

HelloCloud Api allows two kind of grant types:

Client credential
Password

Table 1. Token request parameters
Parameter	Description
Access Token URL	{{base.url}}/Api/access_token
Username	Only available for Password grants. Must be a valid HelloCloud user name.
Password	Only available for Password grants. Password for the selected user.
Client ID	Client ID exists in OAuth2Clients module’s ID. Must be a valid GUID.
Client Secret	Client secret is also in OAuth2Clients module as SHA256 generated value.
Scopes	Scopes haven’t implemented yet

Available parameters

According to JsonApi specification, the available parameters are the following depending on the GET endpoint:

Fields

Fields can filter on attribute object. Allowed keys are valid bean properties.

Example:

{{base.url}}/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Result:

{
    "data": {
        "type": "Account",
        "id": "11a71596-83e7-624d-c792-5ab9006dd493",
        "attributes": {
            "name": "White Cross Co",
            "account_type": "Customer"
        },
        "relationships": {
            "AOS_Contracts": {
                "links": {
                    "related": "/V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493/relationships/aos_contracts"
                }
            }
        }
    }
}

Page

Page can filter beans and set pagination. Allowed key are number and size.

page[number] : number of the wanted page
page[size] : size of the result

Example:

{{base.url}}/V8/module/Accounts?fields[Account]=name,account_type&page[number]=3&page[size]=1

Result:

{
    "meta": {
        "total-pages": 54
    },
    "data": [
        {
            "type": "Account",
            "id": "e6e0af95-4772-5773-ae70-5ae70f931feb",
            "attributes": {
                "name": "",
                "account_type": ""
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                        "related": "/V8/module/Accounts/e6e0af95-4772-5773-ae70-5ae70f931feb/relationships/aos_contracts"
                    }
                }
            }
        }
    ],
    "links": {
        "first": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=1&page[size]=1",
        "prev": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=2&page[size]=1",
        "next": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=4&page[size]=1",
        "last": "/V8/module/Accounts?fields[Account]=name,account_type&page[number]=54&page[size]=1"
    }
}

Sort

Sort is only available when collections wanted to be fetched. Sorting is set to ASC by default. If the property is prefixed with hyphen, the sort order changes to DESC.

Important notice: we only support single sorting right now!

Example:

{{base.url}}/V8/module/Accounts?sort=-name

Result:

{
    "data": [
        {
            "type": "Account",
            "id": "e6e0af95-4772-5773-ae70-5ae70f931feb",
            "attributes": {
                "name": "White Cross Co",
                "account_type": "Customer"
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                        "related": "/V8/module/Accounts/1d125d2a-ac5a-3666-f771-5ab9008b606c/relationships/aos_contracts"
                    }
                }
            }
        },
        {
            "type": "Account",
            "id": "7831d361-2f3c-dee4-d36c-5ab900860cfb",
            "attributes": {
                "name": "Union Bank",
                "account_type": "Customer"
            },
            "relationships": {
                "AOS_Contracts": {
                    "links": {
                         "related": "/V8/module/Accounts/7831d361-2f3c-dee4-d36c-5ab900860cfb/relationships/aos_contracts"
                    }
                }
            }
        }
    ],
}

Filter

Our filter strategy is the following:

filter[operator]=and
filter[account_type][eq]=Customer

Important notice: we don’t support multiple level sorting right now!

Supported operators

Comparison

EQ = '=';
NEQ = '<>';
GT = '>';
GTE = '>=';
LT = '<';
LTE = '<=';

Logical

'AND', 'OR'

Example:

{{base.url}}/V8/module/Accounts?fields[Accounts]=name,account_type&filter[operator]=and&filter[account_type][eq]=Customer

Example:

{{base.url}}/V8/module/Accounts?filter[account_type][eq]=Customer

Result:

Endpoints

Logout

POST {{base.url}}/V8/logout

Get a module by ID

GET {{base.url}}/V8/module/{moduleName}/{id}

Available parameters: fields

Example:

V8/module/Accounts/11a71596-83e7-624d-c792-5ab9006dd493?fields[Accounts]=name,account_type

Get collection of modules

GET {{base.url}}/V8/module/{moduleName}

Available parameters: fields, page, sort, filter

Example:

V8/module/Accounts?fields[Accounts]=name,account_type&page[size]=4&page[number]=4

Create a module record

POST {{base.url}}/V8/module

Example body:

{
  "data": {
    "type": "Accounts",
    "id": "86ee02b3-96d2-47b3-bd6d-9e1035daff3a",
    "attributes": {
      "name": "Test account"
    }
  }
}

Update a module record

PATCH {{base.url}}/V8/module

Example body:

{
  "data": {
    "type": "Accounts",
    "id": "11a71596-83e7-624d-c792-5ab9006dd493",
    "attributes": {
      "name": "Updated name"
    }
  }
}

Delete a module record

DELETE {{base.url}}/V8/module/{moduleName}/{id}

Get relationship

GET {{base.url}}/V8/module/{moduleName}/{id}/relationships/{relatedModuleName}

Example:

V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts

Create relationship

POST {{base.url}}/V8/module/{moduleName}/relationships

Example body:

{
  "data": {
    "type": "Contacts",
    "id": "129a096c-5983-1d59-5ddf-5d95ec91c144"
  }
}

Delete relationship

DELETE {{base.url}}/V8/module/{moduleName}/{id}/relationships/{relatedModule}/{relatedBeanId}

Example:

V8/module/Accounts/129a096c-5983-1d59-5ddf-5d95ec91c144/relationships/Accounts/11a71596-83e7-624d-c792-5ab9006dd493