HRider
| HRider API
Español | English

Introducción

La API de HRider pone a tu disposición diversos Web Services RESTful con los que podrás:
  • Crear y modificar Compañías.
  • Crear y modificar Administradores.
  • Asignar a un administrador permisos para administrar una o más compañías.
  • Crear y modificar Departamentos y Puestos.
  • Crear y modificar Empleados.
  • Asignar las relaciones de supervisor y cliente a un empleado.
  • Obtener las Evaluaciones para una compañía.
  • Obtener y reenviar Invitaciones para participar en una evaluación.
  • Obtener los informes globales para una evaluación.
  • Obtener los informes personales para un empleado en una evaluación.
La API está diseñada siguiendo el principio HATEOS (Hypermedia as the Engine of Application State), lo que permite una sencilla y consistente forma de utilizar y descubrir la API siguiendo los enlaces que cada recurso proporciona. En la sección Java puedes ver cómo sería utilizar la API desde un lenguaje de programación y la simplicidad y elegancia del código cliente que este principio proporciona.
El siguiente diagrama UML muestra las recursos conceptuales principales con los que la API trabaja y cómo se relacionan entre ellos:
Premium Account. Una cuenta PREMIUM puede crear tantas Compañías y Administradores como quiera. Cada Administrador puede tener permiso para acceder a varias compañías.

Departament / Position. La organización de una Compañía tiene una estructura de árbol en la que los nodos son Departamentos y las hojas del árbol son Puestos de trabajo. Un Departamento puede tener uno o ningún departamento padre, y un Puesto siempre pertenecerá a un único Departamento.

Employee. Los empleados de una compañía pueden mantener tres tipos de relaciones con otros empleados: supervisor, cliente y colega. Un empleado puede tener uno o ningún supervisor asignado, así como ninguno o varios clientes. La relación "colega" queda implícitamente establecida por la relación que mantiene un empleado con el resto de empleados de su mismo puesto.

Appraisal / Report / FeedbackReport. Cada una de las evaluaciones creadas con HRider pueden generar diferentes informes (Reports) según su tipo. Además, en el caso de evaluaciones de feedback, un evaluado podría tener también su propio informe personal (FeedbackReport).

Invitation. Los empleados que participan en una evaluación reciben una invitación para participar en ella como evaluadores. La invitación se envía por email y da acceso a completar las encuestas asignadas al evaluador.

Obtener una API Key

Para empezar debemos obtener una API Key que incluiremos en la cabecera de cada llamada a la API y que nos autentificará para realizar las diferentes operaciones. Para hacerlo, el propietario de la cuenta PREMIUM debe acceder a HRider y desde Mi Cuenta acceder al menú Conexiones > API Keys y hacer click sobre el botón Crear Nueva:
Es posible crear tantas API Keys como se quiera y asignar a cada una de ellas diferentes permisos. Desde la pantalla de edición de la API Key se especifica a qué compañías tiene acceso la API Key, y desde Permisos si el acceso será de lectura/escritura o solo lectura para cada uno de los recursos:
Para más seguridad, desde IPs permitidas, se puede especificar una lista de IPs (separadas por comas) para las que únicamente se permitirá el acceso. Cualquier otra llamada desde una IP no incluida será rechazada.

Autentificación

La API key obtenida se debe incluir en la cabecera "authorization" en cada una de las llamadas realizadas. Si la API key fuera oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN y quisiéramos obtener los recursos raíz de la API, la llamada desde Curl podría ser:

curl -i -X GET 'https://dev.hrider.net/api/v1' \
-H 'authorization: bearer oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN'
                    

Conceptos

› Formato

Todos los Web Services retornan un objeto JSON expresado en lenguaje HAL, que está formado de 3 partes:
  • Los atributos del propio objeto
  • Un atributo _links que contiene enlaces a otros recursos con los que el objeto está relacionado
  • Un atributo _embedded con un resumen de cada uno de los objetos con los que se relaciona.

Aquí tenemos un ejemplo con el JSON de un objeto Employee cualquiera:

    {
        "_embedded":{
                "company":{
                    "id":8113,
                    "name":"ACME SOLUTIONS"
                },
                "position":{
                    "id":8348,
                    "code":"W.DESIGNER",
                    "name":"WEB DESIGNER"
                },
                "supervisor":{
                    "id":9121,
                    "code":"EMP001", 
                    "email":"emp001@acme.com", 
                    "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":"lawrence@acme.com",
        "externalId":null,
        "firstName":"LAWRENCE",
        "gender":"male",
        "hireDate":null,
        "id":12430,
        "lastName":"WISE",
        "nationalId":"",
        "phone":"1-541-754-3010",
        "phone2":"",
        "photo":153648986024067666,
        "postalCode":"47096",
        "province":""
}                        
                    
  • El atributo _embedded contiene un resumen de cada uno de los objetos con los que el empleado se relaciona. En este caso incluye un resumen de los datos de su compañía, puesto de trabajo y supervisor actualmente asignado. El resto de objetos retornados por la API siguen la misma lógica.
  • El atributo _links contiene enlaces a los recursos con los que se relaciona y, cuando el objeto relacionado puede existir de forma independiente, permite también establecer o eliminar la relación entre ellos. En el caso de un empleado, los enlaces son:
    En general, el content-type de las peticiones POST para crear y actualizar recursos es application/json, para crear y eliminar relaciones entre recursos se utiliza text/uri-list con la lista de URIs (una por línea) de los recursos a relacionar. Puedes ver un ejemplo de como asignar a un administrador dos compañías aquí.
  • Las fechas se expresan en formato UTC yyyy-MM-ddTHH:mmZ

› Correlación entre IDs

Para correlacionar los empleados de HRider con los que tengamos en nuestro propio sistema el recurso Employee incorpora el atributo externalId. Si lo establecemos, podemos luego sustituir el ID del empleado en HRider con el valor que le hayamos dado utilizando el prefijo 'external-id=' en cualquiera de la URIs utilizadas. Por ejemplo, si creamos un empleado con al atributo externalId 5678 y su ID en HRIder es 1234, estas dos llamadas para obtener el empleado son equivalentes:

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'


Esto permite que podamos referenciar al empleado desde nuestro sistema cuando llamamos a la API sin necesidad de conocer el ID que tiene en HRider.

› Navegación

La forma más fácil de trabajar con la API es navegar por ella mediante los enlaces que la propia API retorna. Podemos empezar obteniendo el punto de anclaje principal que corresponde con la ruta a la versión de la API (v1):

curl -i -X GET 'https://dev.hrider.net/api/v1' -H 'authorization: bearer yourAPIKey'
                    
La respuesta obtenida es:

{
    "_embedded":null,
    "_links":{
            "self":"v1",
            "companies":{"href":"v1/companies"},
            "administrators":{"href":"v1/administrators"},
            "files":{"href":"v1/files"}
    }
}
                    
El objeto contiene los enlaces de primer nivel de la API, y como vemos incluye en su ruta la misma versión de la API que se utilizó en la petición:
  • companies. Enlace para trabajar con compañías.
  • administrators. Enlace para trabajar con administradores.
  • files. Enlace para trabajar con ficheros.

› Paginación

Algunos servicios pueden contener una colección de objetos demasiado grande para obtenerlos todos en una única llamada. En estas situaciones, la respuesta se pagina con un número limitado de resultados y es necesario navegar por el resto de páginas para obtener los siguientes objetos de la colección. Para navegar por la colección se utilizan los parámetros page y pageSize:

En el caso por ejemplo de empleados, la petición:

curl -i -X GET 'https://dev.hrider.net/api/v1/companies/8113/employees?pageSize=2' \
-H 'authorization: yourAPIKey'
                    


Retorna un objeto del tipo colección con únicamente 2 empleados por página del tipo:

{
    "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
    }
}                        
                    

Para navegar a la siguiente página podemos utilizar el link _next. Puesto que se trataba de la primera página el valor del link _previous es null, en cualquier otro caso podemos utilizarlo para navegar a la página anterior. El atributo total nos indica el número total de empleados en la colección.

Errores

La API retorna errores HTTP junto con un objeto JSON que amplía la información del error con los atributos:
  • code. Código de error interno de HRider
  • status. Código de error HTTP
  • message. Mensaje de error
  • description. Descripción del error
La petición a un objeto que no existe retorna una error HTTP 404 (Not found) de este estilo:
      
HTTP/2 404 
content-type: application/json
content-length: 93

{"code":"E001","status":404,"message":"Not found","description":"Employee '124301' not found"}                    
                    
La siguiente tabla muestra todos los códigos de error existentes con los códigos de estado HTTP que pueden contener: