Header Ads Widget

Ticker

6/recent/ticker-posts

¿Qué formatos de datos debe admitir mi API?

 

¿Qué formatos de datos debería admitir mi API?

Al considerar el diseño, la implementación y el mantenimiento de las API, uno de los factores más importantes a considerar son los formatos de datos : cómo la API maneja la interacción entre la generación de datos y la solicitud de datos. Este camino entre la generación y la manipulación, típicamente entre el servidor y el cliente, es el quid del ecosistema API.

En consecuencia, los tipos de formato de datos que se admiten en un ecosistema de API son increíblemente importantes y podrían ser la diferencia entre una API eficaz y potente y un kit infrautilizado. Adoptar el formato correcto hace que una API sea funcional y útil .

Hoy, presentamos una descripción general de los formatos de datos (JSON, XML, YAML, etc.) con los que suelen tratar las API. Analizaremos las diferencias entre cada uno y describiremos por qué un determinado formato puede ser mejor que otros para la situación específica de su API.

Por qué es importante la compatibilidad con el formato de datos

Una API es un puente que conecta usuarios, servicios y fuentes dispares con otros usuarios, servicios y fuentes. Esa es la definición más inclusiva de una API: independientemente de lo que haga una API, cómo lo haga o por qué lo haga, una API es un puente entre dos puntos. Sin embargo, la cuestión que nos ocupa es cómo se atraviesa ese puente. La conexión a los recursos en una API debe representarse de una manera que sea utilizable para la parte solicitante y reconocible de una manera relevante para el tipo de datos que se presentan.

Esta es la razón por la que las opciones de soporte de formato de datos son tan importantes: una API increíble, con una arquitectura , implementación y estrategia de marketing maravillosas estará muerta en el agua si el soporte de formato de datos es incorrecto. La elección inicial del formato de datos de la API determinará la eficacia de la API, lo que afectará las tasas de uso, el éxito de las llamadas de rutina o específicas y la curva de adopción y retención a largo plazo durante la duración de su ciclo de vida .

Formatos comunes de la industria

Ahora veremos varios tipos de formatos de datos. Vamos a separar los idiomas de la industria más comunes del día en cuatro categorías generales:

  • Formatos de datos directos
  • Formatos de datos de feeds
  • Formatos de manipulación de datos
  • Formatos de datos de base de datos

Como ocurre con muchos intentos de categorización, existe una cierta superposición entre estas distinciones. Sin embargo, para facilitar esta conversación, estos idiomas se agruparán por su especialidad en lugar de por su amplio propósito de soporte.

Formatos de datos directos

Los formatos de datos directos están diseñados para manejar datos directamente entre máquinas. Estos lenguajes a menudo se denominan legibles por máquina , ya que tienden a ser densos y compactos. Esto significa que son excelentes para la integración máquina-máquina y / o la manipulación con otras API.

Los formatos de datos directos se utilizan mejor cuando API o servicios adicionales requieren un flujo de datos de su API para funcionar. Los tres formatos más comunes en esta categoría son JSON, XML y YAML.

JSON

JSON (JavaScript Object Notation) es un formato maravilloso cuando se trata de manejar secuencias de comandos del lado del cliente, y es un contrapunto generalmente más rápido a otras opciones como XML. En muchos sentidos, puede que no sea tan poderoso o tan utilizado como otras opciones, pero admite muchas características que hacen que su adopción sea una opción poderosa.

Por ejemplo, JSON admite una distinción entre número, cadena y booleano de la que carece XML (como se ve a continuación en un ejemplo de "puerta de edad"); Sin embargo, como contraargumento, XML maneja el contenido mixto mucho mejor que JSON, especialmente en el caso de matrices de nodos mixtos que requieren expresiones detalladas.

{
	"title": "Age Gate",
	"type": "object",
	"properties": {
		"firstName": {
			"type": "string"
		},
		"knownValue": {
			"type": "boolean"
		},
		"age": {
			"description": "Age in years",
			"type": "integer",
			"minimum": 18
		}
	},
	"required": ["firstName", "lastName"]
}
Los formatos son uno de los pilares del diseño de API evolucionables para la Web.

XML

XML (Lenguaje de marcado extensible) también tiene grandes ventajas. Si bien es casi omnipresente, con una gran base de instalación, su mayor fortaleza puede ser su mayor debilidad. ¿Es la mayor fortaleza? Es el “fregadero” de los formatos, echando todo lo que puede. ¿Su principal negativo? Es el “fregadero” de los formatos, echando todo lo que puede.

Si bien tener todas las herramientas que pueda necesitar a su disposición es una gran ayuda en concepto, hace que XML sea pesado y lento, y con un manejo ya ineficiente de ciertos cálculos (especialmente en el ámbito de la transformación XML), los desarrolladores a menudo se enfrentan a elección entre más funcionalidad con menor velocidad (XML) o menos funcionalidad con más eficiencia (JSON).

A continuación se muestra un ejemplo de un esquema mixto que refleja la puerta de la antigüedad y extiende la funcionalidad del ejemplo JSON anterior.




  
    
    
    
  

YAML

YAML ( YAML Ain't Markup Language ) es "un estándar de serialización de datos amigable para todos los lenguajes de programación". Donde JSON es liviano con un conjunto de características algo laxo, y XML es detallado pero a menudo un poco engorroso, YAML es fácil de leer, liviano y, en general, está en la "mitad del camino". Si bien se clasifica como un formato de datos directo debido a cómo se usa para analizar los ajustes de configuración y las consultas relacionales, muchos sistemas lo usan como una base de datos plana básica.

A continuación se muestra una implementación simple de age-gate que llama a archivos en el servidor dadas ciertas condiciones.

# failover url
url_403: /
#url_403: http://example.org/underage

# snippet definition
snippet_enter: /templates/verified.html.twig
snippet_exit:  /templates/underageexit.html.twig
snippet_403: /templates/validate.html.twig

# minimium age config
min_age: 18

# container variable
width: 300
height: 300

# container bg
overlay: '#ffffff'

Técnicamente, un superconjunto de JSON, YAML es adoptado por muchos por su legibilidad, la capacidad de revelar jerarquías fácilmente y una cantidad mínima de cruft. También tiene una amplia base de herramientas bien conocidas y entendidas: RAML es un lenguaje basado en YAML para describir API, por ejemplo. YAML también se usa ampliamente en servidores de juegos, con servicios como Bukkit que lo usan para unificar las modificaciones del cliente con los servidores de Minecraft para aumentar las llamadas API oficiales en formas nuevas y salvajes.

Formatos de datos de feeds

Los formatos de datos de alimentación son una bestia completamente separada. Aunque todavía se consideran centrados en la máquina, los formatos de alimentación están más vinculados a la utilidad del usuario que a la usabilidad de la máquina. Estos formatos están diseñados para alertar a los usuarios sobre un cambio en la base de código, alertas de cambios en las páginas web y administración de diversas modificaciones en dominios y servicios. Los formatos de esta categoría incluyen RSS, Atom y SUP.

Los formatos de datos de feeds se utilizan normalmente para serializar actualizaciones de varios servidores, sitios o interfaces de front-end, y alertar a los usuarios sobre estos cambios. Estos cambios pueden importarse e integrarse automáticamente, marcarse como una actualización o modificarse para su uso.

RSS

RSS ( Rich Site Summary ) es el formato de datos de feeds más extendido. RSS se ha consolidado como la metodología de alimentación "oficial" de WordPress y otras plataformas de blogs. Es un formato muy simple de usar, pero tiene problemas importantes a pesar de su simplicidad. RSS excluye el marcado XML bien formado, favoreciendo simplemente el texto sin formato y el HTML de escape, y carece de soporte para muchos campos que podrían convertirlo en un sistema mucho más poderoso de lo que es actualmente.

Átomo

Atom , por otro lado, fue diseñado para rectificar estos problemas. Creado desde cero para admitir el descubrimiento y la identificación automáticos, así como el marcado y los medios más complejos, Atom es el hermano mayor de RSS. Desafortunadamente, esta integración tiene un costo. Si bien más medios y marcado es una gran cosa, hace que el sistema sea más propenso a intrusiones a través de código malicioso y, en general, el sistema es más pesado, lo que resulta en una disminución del rendimiento. Esta reducción en la seguridad posiblemente pueda mitigarse mediante una sólida cultura interna de seguridad , pero en cierto punto, podría ser un salto demasiado lejos para ser aceptado por muchos desarrolladores.

Tanto RSS como Atom se manejan típicamente a través de protocolos de alimentación simples que son estándar de la industria; debido a esto, la implementación de RSS y Atom simplemente se reduce a vincular estas URL y sus recursos relevantes a comportamientos específicos en la API. Además, hay una serie de API de terceros que facilitan enormemente la adición de estos feeds. Por ejemplo, la API de Google Feed implementa esto con simples llamadas de JavaScript :

 

 

SORBER

SUP (Protocolo de actualización simple) es el epítome de "jack de todos los oficios, maestro de ninguno". Si bien toma lo mejor de RSS y Atom, siendo más rápido que Atom y más detallado que RSS, viene con los aspectos negativos de ambos formatos. Es más rápido que Atom, pero admite menos formatos multimedia. Es más detallado que RSS, pero no es tan extensible como Atom. Es un buen enfoque "en el medio del camino", pero en realidad es una opción mediana que promedia la velocidad con la utilidad.

{ "updated_time": "2009-04-28T21:29:20Z",
  "since_time": "2009-04-28T21:24:19Z",
  "period": 300,
  "available_periods": {
    "300": "http://gdata/youtube.com/sup?seconds=300",
    "600": "http://gdata/youtube.com/sup?seconds=600",
    "900": "http://gdata/youtube.com/sup?seconds=900"
  },
  "updates": [
    ["159aa827", "6e19"],
    ["9559d1d", "6e19"],
    ["159aa827", "6f22"],
    ````
  ]
}

El ejemplo anterior está tomado de la guía oficial de especificaciones de SUP .

Formatos de manipulación de datos

Los formatos de datos de manipulación deben considerarse más un "envoltorio" que un "formato". Estos formatos están destinados a ser digeridos por aplicaciones en una máquina cliente, en lugar de ser digeridos por un servidor o servicio. En este caso, la envoltura es simplemente un servicio de entrega, no un servicio de análisis o traducción. Los formatos de esta categoría incluyen PDF y KML .

Esta diferencia entre envoltorio y formato es fundamental para comprender este tipo. Los formatos de datos de manipulación son de naturaleza transformadora. Alguien que envía un PDF no está enviando un código para ser digerido simplemente por una máquina, está enviando un PDF para que un cliente lo abra, lo firme, manipule o presente en el navegador a través de extensiones. Alguien que envía un KML no quiere que su archivo se interprete de ninguna otra forma que no sea un contenedor para geocaching o coordenadas de Google Maps .

Esto hace que el formato sea muy específico, por supuesto. Si una API maneja ubicaciones, especialmente en términos de geografía en un servicio de mapas, KML debe ser compatible. Si una API maneja servicios de autenticación de firmas para documentos, se requiere compatibilidad con PDF. Si una API nunca maneja este tipo de datos, entonces realmente no hay ningún caso de uso para el formato.

Lea también: Principales formatos de especificación para API REST

Formatos de datos de base de datos

Finalmente, los formatos de datos de bases de datos son aquellos formatos que se utilizan normalmente para manejar la comunicación entre bases de datos y otras bases de datos o usuarios, una función cada vez más común en un mundo cada vez más afectado por la pila de la nube . Mientras que los formatos de datos directos forman datos a pedido y los manejan de un servicio a otro, los formatos de datos de bases de datos toman los datos generados y los archivan para su uso posterior. Los formatos de esta categoría incluyen CSV y SQL. El soporte en este ámbito tiene que ver con la forma en que se almacenan los datos localmente y los servicios a los que pretende conectarse.

CSV

CSV (valores separados por comas) es un formato muy común, aunque XML lo ha dejado obsoleto en gran medida. Sin embargo, todavía tiene uso, especialmente cuando se considera dentro del contexto de extracción de datos de las plataformas MediaWiki, que maneja la transformación de datos de una forma a otra. Sin embargo, contrasta marcadamente con SQL en que se usa más a menudo para transformar que para almacenar.

A continuación se muestra una implementación simple de un analizador CSV:

fetchOne();

//get 25 rows starting from the 11th row
$res = $csv->setOffset(10)->setLimit(25)->fetchAll();

SQL

El almacenamiento de datos se maneja con mayor frecuencia mediante el formato SQL, en gran parte debido al archivo y la estructura relacional, así como a la adopción empresarial generalizada de SQL y la implementación de MySQL relacionada.

Esta maravillosa implementación de la página de implementación php-sql-parser de code.google.com muestra lo fácil que se integra SQL en un sistema que utiliza PHP:

Array
(
    [OPTIONS] => Array
        (
            [0] => STRAIGHT_JOIN
        )      
       
    [SELECT] => Array
        (
            [0] => Array
                (
                    [expr_type] => colref
                    [base_expr] => a
                    [sub_tree] =>
                    [alias] => `a`
                )

            [1] => Array
                (
                    [expr_type] => colref
                    [base_expr] => b
                    [sub_tree] =>
                    [alias] => `b`
                )

            [2] => Array
                (
                    [expr_type] => colref
                    [base_expr] => c
                    [sub_tree] =>
                    [alias] => `c`
                )

        )

    [FROM] => Array
        (
            [0] => Array
                (
                    [table] => some_table
                    [alias] => an_alias
                    [join_type] => JOIN
                    [ref_type] =>
                    [ref_clause] =>
                    [base_expr] =>
                    [sub_tree] =>
                )

        )

    [WHERE] => Array
        (
            [0] => Array
                (
                    [expr_type] => colref
                    [base_expr] => d
                    [sub_tree] =>
                )

            [1] => Array
                (
                    [expr_type] => operator
                    [base_expr] => >
                    [sub_tree] =>
                )

            [2] => Array
                (
                    [expr_type] => const
                    [base_expr] => 5
                    [sub_tree] =>
                )

        )

)

Funcionalmente, la diferencia es de motivo. Cuando se manejan múltiples bases de datos que se comunican entre sí, SQL es el formato de elección, ya que SQL se usa para organizar datos y manejar llamadas entre esos datos. Cuando se maneja una sola base de datos o un archivo de base de datos plano utilizando algo como YAML que necesita ser traducido a otro formato, CSV es el formato de elección.

¿Cómo afecta Hypermedia a las API?

El gran cambio de formatos de API en los últimos diez años ha alterado el panorama de las API. Desde la amplia adopción de la World Wide Web, los datos se han alejado cada vez más del contenido descriptivo estático y se han orientado hacia datos interactivos y manipuladores, denominados hipermedia . Una extensión de "hipertexto", hipermedia vincula objetos, videos, música y otros medios a otras fuentes similares .

Existe una línea estricta entre "medios" e "hipermedia". Mientras que los medios son simplemente una colección de texto, gráficos, audio o video, los hipermedios son la unión de la interactividad con estos otros formatos de medios. En consecuencia, los formatos han tenido que cambiar para apoyar esta revolución. Por lo tanto, el manejo de códecs, formatos de archivo, etiquetado, orientación a objetos, manejo de bases de datos y más se han vuelto increíblemente importantes.

Mientras hablamos de formatos de datos, tenga esto en cuenta: si bien los formatos de datos son increíblemente importantes, la forma en que se utilizan tiene mucho que ver con el tipo de medio que pretende manejar y si es de naturaleza hipermedia. Su API puede manejar datos de video como un sueño, pero sin una fuente RSS para notificar a los usuarios sobre contenido nuevo, es posible que no tenga audiencia.

Para obtener más información sobre Hypermedia, lea: Cómo mejorar la experiencia de API usando Hypermedia

Conclusión

El soporte de formato de datos tiene mucho que ver con su caso de uso distinto y particular. Si bien, en teoría, podría gastar la totalidad de su presupuesto de desarrollo expandiendo el soporte de formato y la traducción de su API para admitir cualquier cosa que se le presente, finalmente terminará con una API inflada que requiere más soporte con mayor probabilidad de falla. Sin embargo, si se esfuerza demasiado y solo admite uno o dos formatos, y formatos raros, corre el riesgo de ser ágil y esbelto pero, en última instancia, inútil.

Entonces, la pregunta que se debe hacer se reduce a esto: "¿alguien puede esperar razonablemente este formato en el uso de la API?" Si tuviera que usar su propia API, ¿esperaría soporte para el formato que está considerando? Si es así, ¡impleméntalo! Si no es así, considere si hay una mejor opción y apóyelo.

Comprender simplemente lo que hace cada formato es muy importante para saber si desea admitirlo o no. En resumen:

  • Formatos de datos directos (JSON, XML, YAML) : los formatos que admiten el intercambio de datos directamente para su uso en otros sistemas, se utilizan mejor en implementaciones de API de cara al público o B2B
  • Formatos de datos de alimentación (RSS, Atom, SUP) : los formatos que serializan los cambios y actualizan a los usuarios sobre estos cambios, se utilizan mejor en industrias de suscripción como blogs, uso compartido de videos y redes sociales
  • Formatos de manipulación de datos (KML, PDF) : los formatos en los que los datos se envuelven para compartir en forma de documento se utilizan mejor en las industrias orientadas al diseño y la comunicación.
  • Formatos de datos de bases de datos (CSV, SQL) : los formatos en los que los datos se clasifican y almacenan en formatos de bases de datos para su interpretación, se utilizan mejor en implementaciones analíticas dependientes o de uso de datos a largo plazo

En última instancia, los formatos se reducirán a lo que sea mejor dada su implementación específica. Además, el antiguo argumento arquitectónico y de desarrollo de un argumento ágil y rápido frente a un argumento lento y expansivo debe ser una consideración seria; equilibre estas funciones con los requisitos y expectativas del usuario medio, y seguro que encontrará el éxito de la API.

Publicar un comentario

0 Comentarios