JSON API
Before you start calling endpointsAuthenticationAvailable parametersEndpointsLogoutGet a module by IDGet collection of modulesCreate a module recordUpdate a module recordDelete a module recordGet relationshipCreate relationshipDelete relationship
Before you start calling endpoints
Please check the following below:
Composer
Install composer packages with
composer install
Generate private and public.key for OAUTH2
HelloCloud Api uses OAuth2 protocol, which needs public and private keys.
First, open a terminal and go to {{base.url}}/Api/V8/OAuth2
Generate a private key:
openssl genrsa -out private.key 2048
Then a public key:
openssl rsa -in private.key -pubout -out public.key
If you need more information about generating, please visit this page.
The permission of the key files must be 600 or 660, so change it.
sudo chmod 600 private.key public.key
Also, you have to be sure that the config files are owned by PHP.
sudo chown www-data:www-data p*.key
Update encryption key
Now update its value with generating a new one using base64_encode(random_bytes(32))
If you need more information about this issue, please visit this page.
Authentication
HelloCloud Api allows two kind of grant types:
-
Client credential
-
Password
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