The Hrider API offers you various RESTful Web Services, with which you can:
- Create and modify Companies.
- Create and modify Administrators.
- Assign to an administrator permissions to manage one or more companies.
- Create and modify Departments and Job Positions.
- Create and modify Employees.
- Assign supervisor and clients relationships to an employee.
- Obtain company's Appraisals
- Obtain and resend Invitations to take part in an appraisal.
- Get the global reports for an appraisal.
- Get the personal reports for an employee in an appraisal.
The API is designed following the
HATEOS (Hypermedia as the Engine of Application State) principle,
allowing a simple and consistent way to use and discover the API by following the links that each resource provides.
See in the
Java section what it would be like to use
the API from a programming language and the simplicity and elegance of the client code that this principle provides.
The following UML diagram shows the main conceptual resources the API works with and how they relate to each other:
Premium Account.
A PREMIUM account can create as many Companies and Administrators as they want. Each Administrator can
have permission to access several Companies.
Department / Position.
The organization of a Company has a tree structure where the nodes are Departments and the tree's leaves
are Job Positions. A Department can have one or none parent department, and a Position will always belong
to a single Department.
Employee.
Company's employees can have 3 different types of relationships with other employees: supervisor,
client y colleague. An employee can have one or none assigned supervisor, and none or several clients. The "colleague"
relationship is implicitly established by the relationship that an employee maintains with the rest of the employees in the same position.
Appraisal / Report / FeedbackReport.
Each one of the appraisals created in Hrider can generate different depending on their type.
Furthermore, regarding feedback appraisals, an evaluated person could also have their own personal report (FeedbackReport).
Invitation.
Employees who participate in an appraisal receive an invitation to participate in it as evaluators.
The invitation is sent by email and gives access to complete the surveys assigned to the evaluator.
To get started, get an API Key that will be included in the header of each API call
that will authenticate us to perform different operations.
To do it, the owner of the PREMIUM account logs in Hrider and from
My Account accesses to the
Connections >
API Keys menu and clicks to
Create New:
It is possible to create as many API Keys as wanted and assign different permissions to each one.
From the edit API Key screen it specifies which companies have access to the API Key, and from
Permissions it specifies whether access will be read/write or read-only for each of the resources:
To add security, from allowed IPs, a list of IPs (separated by commas) can be designated
for which only access will be allowed. Any other call from an IP not included in the list, will be rejected.
The API Key obtained must be included in the header "authorization" in each of the calls made.
For example, given the API key
oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN if we want to
get the API root recources, the
Curl call could be:
curl -i -X GET 'https://dev.hrider.net/api/v1' \
-H 'authorization: bearer oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN'
All the Web Services return a JSON object expressed in
HAL Language.
It is made of 3 parts:
- Object own attributes
- An attribute _links containing links to other resources to which the object is related
- An attribute _embedded with a summary of each of the objects with which it is related.
Example of any
Employee object's JSON:
{
"_embedded":{
"company":{
"id":8113,
"name":"ACME SOLUTIONS"
},
"position":{
"id":8348,
"code":"W.DESIGNER",
"name":"WEB DESIGNER"
},
"supervisor":{
"id":9121,
"code":"EMP001",
"email":"[email protected]",
"firstName":"ROGER",
"lastName":"OLIVER",
"photo":"12345"
},
"clients":[]},
"_links":{
"self":{"href":"/v1/companies/8113/employees/12430"},
"company":{"href":"/v1/companies/8113"},
"position":{"href":"/v1/companies/8113/employees/12430/position"},
"supervisor":{"href":"/v1/companies/8113/employees/12430/supervisor"},
"subordinates":{"href":"/v1/companies/8113/employees/12430/subordinates"},
"clients":{"href":"/v1/companies/8113/employees/12430/clients"},
"photo":{"href":"/v1/companies/8113/employees/12430/photo"},
"photoContent":{"href":"/v1/companies/8113/employees/12430/photo?alt=media"}},
"address":"7292 Dictum",
"birthDate":"1976-01-04T23:00Z",
"city":"San Antonio",
"code":"EMP002",
"country":"USA",
"dateCreated":"2020-06-09T09:45Z",
"dateModified":"2017-07-19T07:17Z",
"email":"[email protected]",
"externalId":null,
"firstName":"LAWRENCE",
"gender":"male",
"hireDate":null,
"id":12430,
"lastName":"WISE",
"nationalId":"",
"phone":"1-541-754-3010",
"phone2":"",
"photo":153648986024067666,
"postalCode":"47096",
"province":""
}
-
The _embedded attribute has a summary of each one of the objects in which the employee relates to.
In this case, it includes a summary of its company data, job position and currently assigned supervisor.
The rest of the objects returned by the API follow the same logic.
-
The _links attribute contains links to the resources in which the employee relates to.
When the related object can exist independently, it also allows to establish or eliminate the
relationship between them. In the case of an employee, the links are:
| Name |
Type |
Methods |
Description |
| self |
Resource |
GET |
Link to itself |
| company |
Resource |
GET |
Link to employee's company |
| position |
Relation |
GET/PUT/DELETE |
Link to set the employee's job position. |
| supervisor |
Relation |
GET/PUT/DELETE |
Link to set the employee's supervisor |
| subordinates |
Relation |
GET/PUT/DELETE |
Link to set employee's subordinates. |
| clients |
Relation |
GET/PUT/DELETE |
Link to set employee's clients |
| photo |
Relation |
GET/POST/DELETE |
Link to set and get employee's photo |
| photoContent |
Relation |
GET |
Link to set employee's photo content |
In general,
application/json is the content-type of POST requests to create and update resources,
and to create and delete relations between resources,
text/uri-list is used with
the list of URIs (one per line) of the resources to relate. For more information, see an
example to assign an administrator to 2 companies.
-
Dates are expressed in UTC format yyyy-MM-ddTHH:mmZ
To correlate the Hrider Employees with those we have in our own system,
the Employee resource incorporates the
externalId attribute. If set,
the employee ID in Hrider can be replaced with the value given using the prefix '
external-id=' in any
of the used URIs. For example, creating an employee with the attribute
externalId 5678 and its ID in Hrider being 1234, these 2 calls to obtain the employee are equivalent:
curl -i -X GET 'https://dev.hrider.net/api/v1/companies/12345/employees/1234' \
-H 'authorization: yourAuthAPIKey'
curl -i -X GET 'https://dev.hrider.net/api/v1/companies/12345/employees/external-id=5678' \
-H 'authorization: yourAuthAPIKey'
This allows us to reference the employee from our system when we call
the API without having to know the ID that it has in HRrider.
The easiest way to work with the API is to navigate through the links that the API itself returns.
One way to start is by getting the main anchor point that corresponds to the path to the API version (
v1):
curl -i -X GET 'https://dev.hrider.net/api/v1' -H 'authorization: bearer yourAPIKey'
The response obtained is:
{
"_embedded":null,
"_links":{
"self":"v1",
"companies":{"href":"v1/companies"},
"administrators":{"href":"v1/administrators"},
"files":{"href":"v1/files"}
}
}
The object contains the API's first level links, see that
it includes in its path the same version of the API that was used in the request:
- companies. Link to work with companies.
- administrators. Link to work with administrators.
- files. Link to work with files.
Some of the services may contain a collection of objects too large
to get them all in one call. In this situation, the response is paginated
with a limited number of results, and it is necessary to navigate through the rest
of the pages to obtain the following objects in the collection.
To navigate through the collection,
page and
pageSize parameters are used:
In the example case of Employees, the request:
curl -i -X GET 'https://dev.hrider.net/api/v1/companies/8113/employees?pageSize=2' \
-H 'authorization: yourAPIKey'
Returns an object of the type collection with only 2 employees per page like:
{
"total":17,
"_embedded":{
"employees":[ ... ]
},
"_links":{
"self":{"href":"/v1/companies/8113/employees?pageSize=2&page=1"},
"_next":{"href":"/v1/companies/8113/employees?pageSize=2&page=2"},
"_previous":null
}
}
Use the link
_next to navigate to the next page.
Since it is the first page, the value for the
_previous link is null,
otherwise use it to navigate to the previous page. The
total attribute indicates the total number of employees in the collection.
The API returns HTTP errors along with a JSON object that extends the error information with the attributes:
- code. Hrider internal error code
- status. HTTP error code
- message. Error message
- description. Error description
The request of an object that does not exist returns an HTTP 404 (Not found) error like:
HTTP/2 404
content-type: application/json
content-length: 93
{"code":"E001","status":404,"message":"Not found","description":"Employee '124301' not found"}
The following table shows all the existing error codes with the HTTP status codes that they may contain:
| Code |
Description |
HTTP Status |
| E001 | The requested object does not exist | 404 |
| E002 | Not authorized | 403 |
| E003 | Invalid request | 400 |
| E004 | The uploaded file exceeds the maximum size allowed | 413 |
| E005 | Conflict (For example, another employee with the same code already exists) | 409 |
| E006 | 'URL endpoint' does not exist | 404 |
| E007 | Method not allowed | 405 |
| E008 | Request not acceptable | 406 |
| E999 | Unknown error | 500 |
