API de servicio común

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»
email 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

Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.

A %d blogueros les gusta esto: