--- title: "Using the REST API" url: "https://dev.4hse.com/guides/using-rest-api" description: "Guide to using the 4HSE REST API: authentication, requests, practical examples." --- # 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 [Section titled “Standard API”](#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](https://roy.gbiv.com/pubs/dissertation/rest_arch_style.htm) and provide CRUD operations on resources. For each collection, five basic endpoints are generally available: ``` GET /indexGET /view/POST /create {payload}PUT /update/ {payload}DELETE /delete/ ``` The [JSON](https://www.json.org/) data format is used for exchanging information between client and server. HTTP responses follow the [HTTP status code standard](https://tools.ietf.org/html/rfc2616#section-6.1.1). 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 [Section titled “Authentication”](#authentication) To access the 4HSE API, you must start with authentication. There are two authentication methods: - Oauth2 - Access Token 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. ### Oauth2 [Section titled “Oauth2”](#oauth2) We use the Ppen ID standard to authenticate users. The API endpoint is: `auth.4hse.com/realms/4hse/protocol/openid-connect/token` To obtain a token, the following data are required: - `grant_type` - must be set to `password` - `client_id` - unique client identifier - `username` - your username - `password` - your password Or, if you already have a token: - `grant_type` - must be set to `refresh_token` - `client_id` - unique client identifier - `refresh_token` - the refresh token received in a previous call to the same API When accessing the service for the first time, you must use username and password (in addition to client\_id and client\_secret): ``` REQUEST---URI: auth.4hse.com/realms/4hse/protocol/openid-connect/tokenHost: auth.4hse.comMethod: POSTRequest payload:{ "client_id": "service", "grant_type": "password", "username": "my_username", "password": "my_password",} ``` You will receive a response like the following: ``` RESPONSE---Status Code: 200 OKContent-Type: application/jsonBody:{ "access_token": "433b8caa8ea9839b5a732a9455ee50bef31fe4e0", "expires_in": 300, "token_type": "Bearer", "scope": "openid profile email", "refresh_token": "84c893bdd88fb52400c5d8fc246e81bd544a3486", "refresh_expires_in": 86398} ``` The `access_token` is the bearer token you can use to access all APIs. The response also contains the `refresh_token`, which you can use to obtain a new `access_token` without having to provide username and password. In this case, the call will be: ``` REQUEST---URI: auth.4hse.com/realms/4hse/protocol/openid-connect/tokenHost: auth.4hse.comMethod: POSTRequest payload:{ "client_id": "service", "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 OKContent-Type: application/jsonBody:{ "access_token": "b483aff34847b87786bb1a6c313b9e40b2bcf749", "expires_in": 300, "token_type": "Bearer", "scope": "openid profile email", "refresh_token": "c645d84be64791ccf1ee1f148c4f2281a97ae49b", "refresh_expires_in": 86398} ``` 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=51Host: service.4hse.comMethod: GETContent-Type: application/jsonAuthorization: Bearer b483aff34847b87786bb1a6c313b9e40b2bcf749 ``` In this way, you will receive the code `Success (200)` and the desired list of offices. ### Access Token [Section titled “Access Token”](#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. 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) [Section titled “Authorization (ACL)”](#authorization-acl) All web services are executed within an access control system. The control rules follow the permissions defined for the current user. ``` 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 RequestContent-Type: application/jsonBody:{ "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-534443Host: service.4hse.comMethod: DELETEQuery String Parameters: id: office-1-534443 //(1) force: true //(2) ``` ``` RESPONSE---Status Code: 204 No ContentContent-Type: application/json ``` ## Code Example [Section titled “Code Example”](#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) # ``` 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) # ``` 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) #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_officepayload.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) # ``` 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) # ``` 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. This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.