Las API (interfaz de programación de aplicaciones) permiten a los clientes integrar FMS con sus sistemas, obtener y enviar datos de varias entidades.
El cliente envía solicitudes HTTP al sistema, proporcionando información sobre la acción destinada. Los comandos HTTP usualmente usados en una API:
- GET – leer recursos;
- POST – cambiar el estado de recursos;
El contenido solicitado se proporciona en formato JSON con codificación UTF-8. Si se usa otro formato, hay una especificación en la descripción del método.
El código de estado HTTP identifica el estado de la solicitud, se devuelve un código de estado 200 para solicitudes exitosas. También se recibe la información solicitada desde el servidor. Las respuestas pueden ser diferentes, según el tipo usado de API. Las respuestas de API para diferentes tipos de API se describen en capítulos respectivos.
Si la solicitud enviada produjo un error, el sistema enviará un mensaje de respuesta con un código de estado. Los comunes códigos de estado:
- Código 400 – Bad request (Solicitud incorrecta) – la solicitud de API no fue reconocida;
- Código 401 – Unauthorized (No autorizado) – significa que faltan credenciales de autorización o son incorrectas;
- Código 403 – Forbidden (Prohibido) – significa que el cliente no tiene derecho a acceder al recurso solicitado o realizar la acción solicitada;
- Código 404 – Not found (No encontrado) – significa que no se encontró el recurso solicitado;
- Código 500 – Internal server error (Error interno del servidor) – por favor contacte al soporte técnico de su proveedor.
Los códigos de errores proporcionan información general sobre el tipo del error, permitiendo al usuario identificar la fuente del problema.
Algunas API tienen elementos (parámetros) opcionales en sus respuestas. Estos parámetros opcionales pueden ser omitidos por el sistema por varias razones (no datos, datos incorrectos, timeout de respuesta, etc.). El usuario no puede asumir que los datos opcionales siempre se incluirán en respuestas.
Limitaciones de API
Todas las API tienen una limitación:
- No más de 1000 solicitudes por minuto.
Esta limitación es válida para todas las existentes API de FMS.
Autenticación de API
Se necesita autenticación y autorización de API para gestionar el uso de API para clientes diferentes y su integración con sistemas diferentes. Para hacer una solicitud autorizada a los API de sistema, la aplicación solicitante del cliente debe obtener un API_key (clave de API) en nombre del usuario web.
Los clientes solo pueden obtener un API_key contactando al soporte técnico de su proveedor. El API_key consiste en letras, números y símbolos generados al azar.
Ejemplo de respuesta usando un API_key:
Si el API_key se ha expirado, se ha eliminado o simplemente se ha deshabilitado, el sistema responderá:
Se puede ver los puntos finales de API, los parámetros de solicitudes y las respuestas en “Swagger” haciendo clic en este enlace: https://api.fm-track.com
Nota
Siempre hay que especificar una versión de API en todos tipos de API.
¡Importante!
Debido a desarrollo continuo de ambos API y sistema, el usuario a veces puede recibir parámetros no listados en las descripciones. Se recomienda ignorar los parámetros desconocidos y no documentados en las descripciones de API.
Versionamiento y compatibilidad
La solución de interfaz de programación de aplicaciones (en adelante – API) se actualiza, se mejora y se modifica en varias maneras constantemente. Debido a eso hay que saber qué significa el término “compatibilidad”, teniendo APIs en cuenta, y como afecta al usuario, al usar la solución de API.
Al actualizar una API sucederá uno de los siguientes casos:
- La API es compatible con las versiones anteriores – esto significa que los cambios hechos no afectarán al flujo de trabajo de la API de ningún modo, así que no se crea una versión nueva de la API;
- La API no es compatible con las versiones anteriores – esto significa que algunos componentes de la API fueron cambiados y ya no funcionan en la misma manera cómo funcionaban antes. En este caso se lanza una versión nueva de la API.
La versión de API se considera compatible con las anteriores cuando:
- Se añade un nuevo recurso de API;
- Se añaden nuevos parámetros opcionales de solicitud a la API existente;
- Se añaden nuevos parámetros a las respuestas existentes de la API;
- Se cambia el orden de parámetros en las respuestas existentes de la API;
- Se cambia la longitud o el formato de IDs de objeto u otras cadenas opacas. El usuario puede estar seguro de que los IDs generados por el sistema nunca serán más largos que 255 caracteres, pero los de longitud de 255 caracteres aún deberían manejarse. Por ejemplo, si el usuario usa MySQL, los IDs deberían almacenarse en una columna de tipo código de longitud variable (varchar) COLLATE utf8_bin (la configuración de COLLATE asegura que la búsqueda será sensible a las mayúsculas y minúsculas).
- Se añaden variables nuevos de tipo ENUM – cualquier sistema debería manejar desconocidos variables de tipo ENUM. Si por ejemplo el conjunto del variable se cambia de [Privado, Empresa] a [Privado, Trabajo, Empresa], no debería afectar al sistema de ningún modo.