Anexo 2 lineamientos de la arquitectura de datos para el intercambio de información de datos abiertos
Texto incompleto: 1 de 7 páginas no tienen texto recuperado. Consulta el PDF de origen para esas páginas.
Anexo 2 APIS
ANEXO 2 LINEAMIENTOS DE LA ARQUITECTURA DE DATOS PARA EL INTERCAMBIO DE INFORMACIÓN DE DATOS ABIERTOS Esta especificación permite a los Proveedores de Datos desarrollar puntos de consulta de API (API endpoints) estandarizados para que puedan ser accesados por los Solicitantes de Datos con el objetivo de desarrollar soluciones para el usuario final. La especificación de API está basada en el formato de especificación API Swagger versión 2.0, la cual utiliza servicios REST y formato JSON para el intercambio de datos. En este documento se contienen los elementos de arquitectura que deberán constituir la estructura de los mensajes transmitidos vía APIs, en particular: 1. El significado de los encabezados y cómo deben ser aplicados en el contexto del Proveedor de Datos. 2. Los mensajes de respuesta exitosa y de error que se devuelven como resultado de las peticiones de consulta de datos. Estructura del Mensaje de Datos Los Proveedores de Datos deberán construir el mensaje de datos conforme a la estructura antes mencionada; asimismo, se deberá considerar que todos los campos son obligatorios, a menos que se indique lo contrario. Para efectos de la construcción del mensaje de datos especificado, los Proveedores de Datos podrán utilizar herramientas de desarrollo diferentes a Swagger, siempre y cuando, las herramientas se apeguen a la especificación definida en el presente documento y el Anexo 3 de estas disposiciones. Campos de la estructura del mensaje de acuerdo a la especificación Swagger versión 2.0 Observaciones Title
{
"swagger": "2.0",
"info": {
"version": "v1.0.0", La versión de la especificación de API que se documenta. "title": " Open data ATM API specification" Título de la especificación de API que indica el Dato que se podrá compartir mediante esta. "description": "Location and services offered by ATMs" Descripción de la funcionalidad de la API. },
Host
"host": " openapi.bankname.com”, Es la URI base del Proveedor de Datos "basePath": "/v1.0.0", Es la ruta del recurso. Para este caso, ‘v1’ se refiere a la versión de la especificación de API "schemes": [
"https" Indica que el esquema de comunicación de datos es HTTPS ]
Produces
"produces": [
" application/ json" Indica cómo responderá la API. En este caso, la respuesta es una representación en formato JSON de la especificación contenida en la versión v1.0
Anexo 2 APIS
Tags
"tags": [
{
"name": "ATM",
"description": "Endpoint to request ATM data" Es una etiqueta que indica que las respuestas de datos se relacionan a un recurso de tipo ATM.
Paths
"paths": {
"/atms": { Es el punto de consulta (endpoint, en inglés) para acceder al recurso "get": { El método de solicitud que se utiliza para acceder al recurso. "tags": [
"ATM"
],
"description": "Gets a list of all `ATM` objects.", Descripción de la funcionalidad del método GET Parameters Se refiere a valores que pueden ser incluidos como parte de la petición de consulta que causen que el recurso responda de una manera particular.
"parameters": [
{
"name": "If-Modified-Since", Nombre del parámetro. "type": "string", El tipo de objeto que se espera que sea devuelto. "description": "Used for conditional request, to retrieve data only if modified since a given data", Descripción de la funcionalidad del parámetro. Evita que sea devuelta una carga útil1 completa, si el recurso que se está consultando no ha sido actualizado desde la última vez en que se accedió al mismo. "in": "header", Especifica en donde se debe de devolver el valor, en este caso, en el encabezado del mensaje. "required": false Indica si el valor requiere ser devuelto o no. En este caso, no es requerido. },
{
"name": "If-None-Match", Nombre del parámetro. "type": "string", El tipo de objeto que se espera que sea devuelto. "description": "Used for conditional request, to retrieve data only if the given Etag value does not match", Descripción de la funcionalidad del parámetro. Evita que sea devuelta una
1 En informática, se refiere al término en inglés payload, que es el conjunto de datos que constituyen el contenido utilizable del mensaje transmitido, excluyendo información adicional, como los encabezados.
Anexo 2 APIS
carga útil completa, si el valor de la etiqueta Etag no coincide. "in": "header", Especifica en donde se debe devolver el valor, en este caso, en el encabezado del mensaje.
"required": false Indica si el valor requiere ser devuelto o no. En este caso, no es requerido. }
],
Responses Respuestas de la API a la petición de consulta de Datos. Los códigos de respuesta que se muestran en esta especificación serán mandatorios, el detalle completo se puede consultar en la Tabla de Códigos HTTPS, misma que se describe en este documento. El Proveedor de Datos podrá incluir otros códigos de respuesta estándar, de los definidos por el protocolo HTTPS, en caso de que así lo considere.
"responses": {
"200": { Es el código de respuesta estándar que devuelve el servidor después de la ejecución exitosa del método GET sobre el recurso ATM. "description": "Successful response with a list of `ATM` data",
"headers": {
"Strict-Transport-Security": {
"type": "string",
"description": "HTTPS strict transport security header",
"default": "max-age=31536000" Especifica el tiempo en segundos (un año) en el cual el recurso puede ser accedido mediante el protocolo HTTPS. El código de tiempo de este campo puede ser diferente siempre y cuando su valor no sea menor. },
"Etag": {
"type": "string",
"description": "A unique ID identifying whether this resource has changed" Un identificador único que especifica si el recurso ha sido actualizado o no. },
"Cache-Control": {
"type": "string",
"description": "Describes how long this response can be cached",
"default": "max-age=15552000" Indica que la respuesta puede ser almacenada de manera confiable (cached, en inglés) cierto tiempo antes de consultar
Anexo 2 APIS
al endpoint por alguna actualización. Tratándose de datos abiertos, se definen 6 meses (expresados en segundos), el valor se puede modificar siempre y cuando este número no sea menor.
},
"X-Frame-Options": {
"type": "string",
"description": "Prevent this request from being loaded in any iframes",
"default": "DENY" Previene que la respuesta sea cargada en un marco o frame. },
"X-Content-Type-Options": {
"type": "string",
"description": "Ensures each page has a content type and prevents browsers from doing MIME type sniffing",
"default": "nosniff" Evita que se devuelva otro tipo de formato que no sea JSON }
},
Schema y Meta Data Es la información complementaria de la carga útil; son valores que se deben incluir en el cuerpo de dicha carga útil.
"schema": {
"type": "object", Devuelve un tipo de objeto JSON con los metadatos: LastUpdated; TotalResults; Agreement; License y TermsOfUse. "properties": {
"meta": {
"title": "Meta data",
"type": "object",
"properties": {
"LastUpdated": {
"type": "string",
"format": "date-time" Indica cuándo la carga útil del endpoint fue actualizada la última vez. },
"TotalResults": {
"type": "integer" Indica el número de registros en la carga útil },
"Agreement": { Hace referencia a que existe un acuerdo definido por cada Proveedor de Datos para el uso de la API con relación a los términos y condiciones que establezca dicho Proveedor de Datos. "type": "string",
Anexo 2 APIS
"enum": [
" El uso de la API y el dato que sea intercambiado a través de esta será sujeto a los términos y condiciones establecidos por el Proveedor de Datos"
]
},
"License": { El contenido de los campos License y TermsOfUse será definido por el acuerdo que cada Institución realice con el Solicitante de Datos. "description": "To be confirmed",
"type": "string",
"format": "uri",
"enum": [
" To be confirmed"
]
},
"TermsOfUse": {
"description": " To be confirmed",
"type": "string",
"format": "uri",
"enum": [
"To be confirmed"
]
}
},
"required": [
"LastUpdated", Indica que estos metadatos deben ser devueltos en cada respuesta. "TotalResults", Indica que estos metadatos deben ser devueltos en cada respuesta. "Agreement", Indica que estos metadatos deben ser devueltos en cada respuesta. "License", Indica que estos metadatos deben ser devueltos en cada respuesta. "TermsOfUse" Indica que estos metadatos deben ser devueltos en cada respuesta. ],
"additionalProperties": false
Se puede consultar una versión implementada en la siguiente liga: https://app.swaggerhub.com/apis/CNBV9/atm_open_data_specification/1.0.0 Tabla de Códigos HTTPS Código de respuesta Descripción en inglés Descripción en español 200 Successful response with a list of `ATM` data. Respuesta exitosa con una lista de datos del Cajero Automático 400 You have sent a request which could not be understood. Usted ha enviado una solicitud de consulta que no se entiende. 408 Your client has failed to submit a request, and a timeout has occurred. La solicitud de consulta ha fallado y el tiempo ha caducado.
Anexo 2 APIS
429 You have requested this resource too often. Usted ha solicitado consultar este recurso demasiadas veces. 500 An error occurred on the server. Un error ha ocurrido en el servidor. 503 The service is temporarily unavailable. El servicio no está disponible temporalmente.
Lineamientos relacionados con capacidades de la solución
- I.
El Proveedor de Datos podrá limitar el número de solicitudes a la API para mejorar el desempeño utilizando el algoritmo de bucket de tokens, esto mediante la configuración de dos parámetros:
- a)
Límite de razón de solicitudes (en inglés rate limit) a 3,000 por segundo, que representa el máximo de solicitudes que la API puede atender de forma estable, consistente y exitosa en un periodo de tiempo.
- b)
Límite de ráfaga (en inglés throttling) a 1,000 que representa el número máximo de solicitudes atendidas simultáneamente (1 milisegundo) por la API, sin devolver respuestas 429.
- II.
El Proveedor de Datos podrá cumplir con un nivel de servicio de 5 segundos como tiempo de respuesta por petición a la API, considerando un tamaño máximo de 5MB en la respuesta.
Verifica el texto oficial
- Publicación del documento
- 04 de junio de 2020
- Fecha de versión
- 04 de junio de 2020
- Fecha de esta versión
- 04 de junio de 2020
- Texto indexado
- 6 de 7 páginas
Identificación del anexo: 2 APIS. Fechas de la norma matriz: publicación 04 de junio de 2020; última modificación 04 de junio de 2020.
Fundamento recuperado de preámbulo de la norma matriz, páginas 1–3. Párrafo literal del preámbulo; revisar citas en fuente oficial. Fuente del fundamento ↗