Using the REST API

In this guide, we will describe the architecture of 4HSE and the web services it offers to developers. Afterwards, we will create a code example that includes the use of the API and covers a common development scenario.

Standard API

The 4HSE platform provides a wide set of web services that allow you to manage your project data. All services follow the HTTP REST API standard and provide CRUD operations on resources.

Tip

A resource is a set of attributes (for example, a person is described by first name, last name, etc.). Each resource has an identifier, an id attribute that has a unique value. Resources are grouped into collections based on their type (all resources of type person are collected in the person collection).

For each collection, five basic endpoints are generally available:

GET <collection>/index
GET <collection>/view/<my_resource_id>
POST <collection>/create {payload}
PUT <collection>/update/<my_resource_id> {payload}
DELETE <collection>/delete/<my_resource_id>

Caution

It may happen that a collection does not follow this standard. In any case, all available APIs are using the OpenAPI standard.

The JSON data format is used for exchanging information between client and server.

HTTP responses follow the HTTP status code standard. For example, you will receive a 200 OK code for a response with content, 404 Not Found for an unavailable resource, 500 Internal Server Error for unexpected errors, etc.

Authentication

To access the 4HSE API, you must start with authentication. There are two authentication methods:

• oauth2

• auth_code

Suppose you want to retrieve the list of offices ordered by name; you will need to call the API: service.4hse.com/office/index?sort=-name&limit=50&offset=51

If you make this call without authentication, you will receive the response code Unauthorized (401). You need to use one of the following two methods to make the previous call work.

Note

This is just an example, a more detailed explanation of the APIs and how to call them is in the following chapters.

oauth2

We use the oauth2 standard to authenticate users.

The API endpoint is: service.4hse.com/oauth2/token

To obtain a token, the following data are required:

• client_id - unique client identifier

• client_secret - password associated with the client_id

• username - your username

• password - your password

or, if you already have a token

• client_id - unique client identifier

• client_secret - password associated with the client_id

• refresh_token - the refresh token received in a previous call to the same API

Caution

Each customer who wants to use the API must have their own client_id and client_secret. You must request these credentials from 4HSE support.

When accessing the service for the first time, you must use username and password (in addition to client_id and client_secret):

REQUEST
---
URI: service.4hse.com/oauth2/token
Host: service.4hse.com
Method: POST
Request payload:
{
    "client_id": "example_client_id",
    "client_secret": "example_client_secret",
    "grant_type": "password",
    "username": "example_user",
    "password": "example_password"
}

You will receive a response like the following:

RESPONSE
---
Status Code: 200 OK
Content-Type: application/json
Body:
{
    "access_token": "433b8caa8ea9839b5a732a9455ee50bef31fe4e0",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": null,
    "refresh_token": "84c893bdd88fb52400c5d8fc246e81bd544a3486",
    "user_id": "example_user"
}

The access_token is the bearer token you can use to access all APIs. As indicated, it expires after 86400 seconds (24 hours). The response also contains the refresh_token, which you can use to obtain a new access_token without having to provide username and password. Remember that the refresh_token expires after 14 days. In this case, the call will be:

REQUEST
---
URI: service.4hse.com/oauth2/token
Host: service.4hse.com
Method: POST
Request payload:
{
    "client_id": "example_client_id",
    "client_secret": "example_client_secret",
    "grant_type": "refresh_token",
    "refresh_token": "84c893bdd88fb52400c5d8fc246e81bd544a3486"
}

This call will return a new access_token and a new refresh_token (the previous one will be disabled).

RESPONSE
---
Status Code: 200 OK
Content-Type: application/json
Body:
{
    "access_token": "b483aff34847b87786bb1a6c313b9e40b2bcf749",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": null,
    "refresh_token": "c645d84be64791ccf1ee1f148c4f2281a97ae49b",
    "user_id": "example_user"
}

To make calls to the system using the bearer token, you must add a new header to all requests, for example:

Authorization: Bearer b483aff34847b87786bb1a6c313b9e40b2bcf749

Now we can return to the previous API: service.4hse.com/office/index?sort=-name&limit=50&offset=51. As you recall, without authentication you received the code Unauthorized (401). Now, by adding the authorization header, the call will be:

REQUEST
---
URI: service.4hse.com/office/index?sort=-name&limit=50&offset=51
Host: service.4hse.com
Method: GET
Content-Type: application/json
Authorization: Bearer b483aff34847b87786bb1a6c313b9e40b2bcf749

In this way, you will receive the code Success (200) and the desired list of offices.

Access Token

This method is very simple: just add the access-token query parameter to each API call. You must request your access-token from 4HSE support, who will generate it upon request.

Caution

Warning: this access-token is completely different and has no relation to oauth2.

When you have this token, you can make the same call as before by adding the access-token parameter. If your access token is sample-access-token you can simply call:

service.4hse.com/office/index?sort=-name&limit=50&offset=51&access-token=sample-access-token

In this way, you will receive the code Success (200) and the desired list of offices.

Authorization (ACL)

All web services are executed within an access control system. The control rules follow the permissions defined for the current user.

Tip

Every item in 4HSE is part of a hierarchical dependency structure. If you delete a person, all resources linked to that person (certificates, courses, etc.) will be deleted along with it. This practice preserves data consistency and avoids orphaned items.

    REQUEST
    ---
    URI: service.4hse.com/office/delete/office-1-534443
    Host: service.4hse.com
    Method: DELETE
    Query String Parameters:
        id: office-1-534443                         // (1)
        force: false                                // (2)

Since force=false, the response will be 400 Bad Request and the linked resources will be listed in the body. Each of these resources is identified by id(3), label(4) and type(5).

RESPONSE
---
Status Code: 400 Bad Request
Content-Type: application/json
Body:
{
    "message": "Addictions are present",
    "code": 1001,
    "data": [
        {
            "id": "office-1-534443",            // (3)
            "label": "Office 1",                // (4)
            "type": "OFFICE"                    // (5)
        }
    ]
}

If force=true(2) the resource identified by id(1) and all linked resources will be deleted.

REQUEST
---
URI: service.4hse.com/office/delete/office-1-534443
Host: service.4hse.com
Method: DELETE
Query String Parameters:
    id: office-1-534443                         //(1)
    force: true                                 //(2)

RESPONSE
---
Status Code: 204 No Content
Content-Type: application/json

Code Example

In this example, we will create a simple CRUD application that uses the 4HSE REST API.

Requirements:

• working python 3 environment

• python-requests library

• python-uuid library

Let’s start by writing the code to retrieve a list of offices by calling the office/index service.

import requests                                                          # (1)

params = {'limit': 10, 'sort': '-name'}                                  # (2)
r = requests.get('https://service.4hse.com/office/index', params=params) # (3)
print(r.text) #{data: [{'office_id':'sad14024000hdg002252','name':'My first office', 'project_id':'prj1234567'}], total_count: 1, pos: 0}
print(r) #<Response [200]>

1. Import the library to make http requests

2. Define a set of parameters for the request. In this case, we want to limit the result to 10 resources ordered in descending order by office name.

3. Make the request and print the results.

The next step is to create a new office using the office/create service.

import uuid

project_id = r.json().get('data')[0].get('project_id')   # e.g. prj1234567                           # (1)
office_id = uuid.uuid1()  # e.g. 00a5d37c-4fe2-46ee-b820-77ce0ac22725                                # (2)

payload = {'office_id': office_id, 'name': 'My new office', 'project_id': project_id}               # (3)
r = requests.post('https://service.4hse.com/office/create', data=payload, params=authentication)    # (4)
print(r.text) #{'data': {'office_id': '00a5d37c-4fe2-46ee-b820-77ce0ac22725', 'name': 'My new office', 'project_id': 'prj1234567'} }
print(r) #<Response [201]>

1. A required attribute for the office is the project_id that identifies the project within which we want to create the office. In this example, we retrieve it from the first office returned by the index call.

2. We use the python uuid library to generate a unique identifier for the office.

3. We define a payload that includes office_id, project_id, and the required attribute name.

4. We make the request and print the results.

Now let’s retrieve the newly created office using the office/view service.

params = {'id': office_id}                                              # (1)
r = requests.get('https://service.4hse.com/office/view', params=params) # (2)
print(r.text) #{'data': {'office_id': '00a5d37c-4fe2-46ee-b820-77ce0ac22725', 'name': 'My new office', 'project_id': 'prj1234567'} }
print(r) #<Response [200]>
new_office = r.json().get('data')                                       # (3)

1. Define the parameters including the office_id.

2. Make the request and print the result.

3. Finally, we save the newly created office in the new_office variable.

Now we want to change the office name using the office/update service.

params = {'id': office_id}
payload = new_office
payload.update({'name': 'new name for my office'})                                      # (1)
r = requests.put('https://service.4hse.com/office/update', data=payload, params=params) # (2)
print(r.text) #{'data': {'office_id': '00a5d37c-4fe2-46ee-b820-77ce0ac22725', 'name': 'new name for my office', 'project_id': 'prj1234567'} }
print(r) #<Response [200]>

1. We use new_office as the request payload and modify its name attribute.

2. We make the request and print the result.

Finally, let’s delete the office using the office/delete service.

params = {'id': office_id, 'force': 'true'}                                     # (1)
r = requests.delete('https://service.4hse.com/office/delete', params=params)    # (2)
print(r) #<Response [204]>

1. Define the parameters including the office_id you want to delete and force=true to confirm the deletion.

2. Make the request and print the result.

Note

Sources:

Example REST API client