Descripción general de la API
Las interfaces de programación de aplicaciones (Application Programming Interfaces, API) de servicios web de BEACON utilizan servicios web RESTful para entregar datos en JSON. La mayoría de los entornos de programación tienen bibliotecas disponibles para crear solicitudes HTTP y analizar las respuestas.
API de servicio común
Todos los servicios web de BEACON siguen el diseño de API de servicios comunes.
Códigos de estado HTTP
Estos son los códigos de respuesta estándar que devuelven todos los servicios de BEACON. Consulte cada API para obtener detalles específicos sobre los códigos.
| Código | Descripción |
| 200 OK | Solicitud aceptada y debería incluir algo de contenido, asuma que la operación se completó. |
| 202 Accepted | Solicitud aceptada pero el procesamiento no está completo. El encabezado de la ubicación apunta a un localizador de recursos uniforme (Uniform Resource Locator, URL) que muestra el progreso o el resultado final. |
| 204 No Content | Solicitud aceptada, pero no hay más detalles/contenido al respecto, suponga que la operación se completó. |
| 302 Found | Para redirigir a otro URL, como una descarga. |
| 400 Bad Request | Solicitud mal formateada, es decir, el JSON no es válido en contraposición a una falla de validación (falta un campo obligatorio, fecha que no es una fecha), que es 422. |
| 401 Unauthorized | Sin encabezado de autorización o no autorizado. |
| 403 Forbidden | El usuario no tiene permiso. |
| 404 Not Found | Si no se encuentra algún recurso o página específica, es decir, hwr/account/blah. En el caso de llamadas a listas (es decir, GET/hwrruns), se devolverá una matriz vacía. |
| 409 Conflict | Generalmente, al crear (POST) hay una colisión, consulte las API para obtener información específica. |
| 412 Precondition Failed | Generalmente, en la actualización (PUT/PATCH) hay un problema al cambiar el recurso, consulte las API para obtener información específica. |
| 422 Unprocessable Entity | La solicitud es sintácticamente correcta, pero la entidad no es válida, falta un campo obligatorio o una fecha está fuera de rango. |
| 5xx | Error interno del servidor. |
Objetos de respuesta
Todos los servicios responden sin ambigüedad en el tipo de objeto, es decir, un cliente podrá obtener de forma determinista una respuesta basada en el código de respuesta HTTP. Dependiendo del código de respuesta HTTP, se devuelve el mismo objeto. Algunas respuestas utilizan «envoltorios» de objetos para la paginación.
Cuando una API devuelve códigos 4xx, son respuestas de error estándar.
Un código 2xx devolverá un objeto JSON según la API.
Nombres de propiedad
Todos los objetos JSON usan camelCase, excepto que los uuids sean propiedad con el sufijo de identificador único universal (Universally Unique Identifier, UUID), p. ej., accountUUID, reportUUID, taskUUID, etc.
| tipo | descripción |
| string | cadena |
| int | int |
| float | float |
| bool | booleano |
| Object array | una matriz de tipo de elemento Object |
| uuid | UUID entre comillas, «3287912374838239853» |
| date | cadena entre comillas ISO 8601, «2015-02-03T13:04:24Z» |
| dirección de correo electrónico entre comillas (límite 254), «frank@example.com« | |
| url | url entre comillas, puede ser relativo, «/v1/svc/3323» |
Paginación
La API permite paginar a través de conjuntos de resultados. Los resultados paginados se devuelven en un objeto contenedor de paginación, con los objetos reales bajo una propiedad de resultados. La solicitud de API debe tomar un conjunto estándar de parámetros que indiquen los criterios de paginación.
Parámetros
| parámetro | tipo | descripción |
| offset | int | Compensación del número de registro, comenzando en 0. El primer número de registro después de esta compensación se incluye en los resultados. Predeterminado: 0. |
| limit | int | Número máximo de registros para devolver, hasta un máximo de 100. Se pueden devolver menos registros. Predeterminado: 50. |
| sort | cadena | Campo para ordenar |
| dir | enum | desc | asc. Predeterminado: desc. |
Objeto de respuesta
| propiedad | tipo | descripción |
| total | int | El número total en el conjunto. |
| from | int | El número de registro del primer elemento en los resultados. Los números de registro comienzan en 1. |
| to | int | El número de registro del último elemento en los resultados. |
| results | Matriz de objetos | Una matriz de los objetos de resultado; consulte la API para conocer el tipo de objeto. Será una matriz vacía si el total es 0 y puede estar vacía si no hay resultados que comiencen en la compensación solicitada. |
{
"total": 532,
"from": 101,
"to": 150,
"results": [ {
MY OBJECT
]}
}
Códigos de API
Todos los servicios utilizan un formato de código de API común:
apicode:= [E|W|I|D]-tla-nnn
Cada servicio define los posibles códigos de error y sus significados.
Es decir, E-HWR-200 o W-TSK-56.
Argumentos de código
Algunos códigos pueden requerir argumentos. Estos se pueden utilizar al crear un mensaje de error, p. ej., el código E-HWR-301 podría traducirse en español como «La plantilla clonada ({1}) no existe», donde {1} es el primer valor del argumento, p ej. ,«Carrera invernal».
La propiedad opcional de argumentos en la respuesta de error es una matriz de cadenas.
Códigos de motivo
Los códigos de motivo son puntos no legibles por humanos en el código que indican la ubicación del código de API o la razón subyacente para generar el código. Se pueden encadenar y un servicio debe reenviar códigos de motivo: si el servicio HWR llama al servicio TSK, que devuelve un código de error y un motivo, el HWR debería devolver un nuevo código de API (E-HWR-nnn) y encadenar el código de motivo TSK ( HWR-client.tsk_TSK-run.py:56)
reason:= tla-msg[_reason]* msg:= anyalpha ^_
Respuestas de error
Un servicio que devuelve errores responde con un objeto estándar que contiene al menos el código y el motivo.
{
"code": "E-HWR-200",
"args": ["a code argument"],
"reason": "HWR-client.tsk_TSK-run.py:56
}
Códigos de API comunes
Estos códigos son comunes a todos los servicios.
| Estado HTTP | Código de API | argumentos | descripción |
| 400 | E-API-400 | status code | Un problema interno causado por una solicitud incorrecta. |
| 400 | E-API-450 | lineNbr, colNbr | Excepción general de procesamiento JSON. |
| 400 | E-API-451 | lineNbr, colNbr | Error al analizar JSON. JSON mal construido. |
| 400 | E-API-452 | lineNbr, colNbr | Mapeo de JSON. |
| 400 | E-API-453 | lineNbr, colNbr | Generación de JSON. No se pudo generar una respuesta de JSON. |
| 406 | E-API-406 | Tipo de medio de respuesta aceptada no admitido. | |
| 415 | E-API-415 | El tipo de medio de solicitud de tipo de contenido no es compatible. | |
| 422 | E-API-422 | property:error, … | Fallo de validación. Consulte la API para obtener una descripción de las propiedades requeridas del objeto. |
| 500 | E-API-500 | Error interno del servidor. |
Autenticación
La API utiliza autenticación de acceso básico HTTP para proporcionar a sus aplicaciones acceso seguro a todos los datos disponibles en su cuenta. Además, todas las solicitudes deben pasar por nuestra terminal HTTPS, donde toda la transferencia de datos está encriptada a través de Secure Socket Layer (SSL). Con su nombre de usuario y contraseña de BEACON, puede usar el método base64 de su biblioteca de programación para crear un encabezado de autorización HTTP. Para obtener una explicación de este procedimiento, consulte: http://en.wikipedia.org/wiki/Basic_access_authentication.
Get Support