Header Ads Widget

Ticker

6/recent/ticker-posts

5 consejos de diseño de API más allá de REST

 


En los últimos años, ha habido un aumento masivo en las API web y la adopción de REST. Dado que ambos son tendencia, más desarrolladores afirman estar usando REST incluso si no se adhieren con precisión a las restricciones originales de Roy Fielding. Los desarrolladores también han buscado aclarar aún más el diseño de API con modelos como el Modelo de Madurez de Richardson o el Modelo de Madurez de Seguridad de API , agregando capas adicionales de cumplimiento a los estándares de Fielding.

REST es un conjunto de restricciones arquitectónicas generales. Pero en entornos del mundo real, los desarrolladores de API han llegado a confiar en las mejores prácticas y expectativas adicionales. A continuación, cubriremos algunos consejos para diseñar API web modernas, analizando el uso de formatos de datos, nombres de terminales, códigos de error, paginación y otros consejos para complementar REST.

Quédate con JSON

Técnicamente hablando, una API REST no está limitada a trabajar con un solo tipo de archivo. Las API REST pueden consumir archivos XML y SOAP, por ejemplo. Sin embargo, solo porque puedas no significa que debas hacerlo . Como regla general, JSON debería ser el formato estándar para enviar y recibir datos con una API. Casi todos los formatos web pueden usarlo, por un lado. La mayoría tiene formas integradas de lidiar con JSON de forma nativa. Casi todos los desarrolladores web también lo hacen. Esa es una razón suficiente para elegir JSON sobre otros formatos siempre que sea posible.

Otros formatos de archivo a menudo requieren un procesamiento externo adicional. Los archivos XML a menudo deben convertirse a JSON antes de que puedan consumirse, por ejemplo. También es más desafiante manipular datos XML en el lado del cliente.

Para asegurarse de que siempre está trabajando con JSON, puede especificar el tipo de archivo configurando la Content-typevariable en el encabezado de respuesta para application/jsoncuando se realiza una solicitud. Algunas aplicaciones configuran el encabezado de respuesta en JSON automáticamente, mientras que en otras se debe especificar. También querrá asegurarse de que los puntos finales de su API devuelvan archivos JSON.

Echemos un vistazo a cómo se ve esto en acción. Este es un ejemplo de cómo trabajar con el marco web Express que luego analiza esa solicitud utilizando la body-parserfunción. Luego, el objeto resultante se llama using res.json.

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.post('/', (req, res) => {
  res.json(req.body);
});

app.listen(3000, () => console.log('server started'));

El bodyParser.json()análisis sintáctico de la solicitud JSON en un objeto de JavaScript, que luego se atribuye al req.bodyobjeto.

En la respuesta, establezca el Content-typeencabezado en application/json; charset=utf-8Este método debería funcionar con la mayoría de los marcos web.

Cosas, no acciones

Recuerde, los puntos finales de la API deben categorizarse para que toda la acción se lleve a cabo en el lado de la consulta. Teniendo esto en cuenta, debe nombrar sus puntos finales según los objetos y no las cosas que les están sucediendo. Esto podría terminar siendo interpretado accidentalmente como código por algunos programas.

Imagine que desea recuperar todos los coches de una base de datos de vehículos. Ahora imagine que devuelve todos esos resultados al punto final getCars.

Sin embargo, ese mismo patrón de nomenclatura se usa para objetos en JavaScript. No se sabe qué tipo de estragos podría causar un error tan simple.

Como regla general, asigne nombres a los puntos finales de su API como sustantivos en lugar de verbos. Si necesita especificar o subdividir más, puede manejar eso con más subdivisiones.

Usar nombres lógicos para puntos finales

Una de las principales razones para usar API es hacer que la interacción con nuestros datos sea más manejable. Perdemos esta ventaja si creamos demasiados puntos finales hasta el punto en que sea difícil seguirlos.
Por ejemplo, imagine que mantiene un almacén de piezas de automóvil. Ahora imagina que tienes un punto final para cada tipo de artículo que llevas. En poco tiempo, tienes '/ carHeadrests', 'truckSeatbeltEnclosures', 'carRadialTires' y así sucesivamente. No tomaría mucho tiempo perder el control sobre la cantidad de puntos finales.

Ahora, considere esta alternativa. Tienes un punto final para cada tipo de vehículo, por lo que /trucks/carsy así sucesivamente. A continuación, puede tener partes para cada tipo de vehículo como un subdirectorio: /cars/parts/seatbelts/trucks/tires/whitewallsy así sucesivamente. Esto ayuda a mantener manejable la cantidad de puntos finales. También se adhiere a una estructura comprensible que es fácil de navegar y usar, lo que ayuda a su API a adherirse al principio de Roy Fielding de que las API deben ser autodescriptivas y no requieren documentación externa para usarlas.

Siempre que sea posible, debe intentar agrupar los datos relevantes en un solo punto final. Esta es una buena idea independientemente de cómo esté configurada su base de datos. De hecho, podría ser una buena idea utilizar una estructura diferente para sus puntos finales de API y su base de datos. Esto podría evitar que los ciberdelincuentes obtengan demasiada información sobre la arquitectura de su sistema.

Estos criterios de valoración a continuación, se puede interactuar con a través de su regularidad GETPOSTPUT, y DELETEHTTP comandos.

Utilice códigos de error estándar

Otra de las principales razones por las que la gente usa las API es para familiarizar los datos y las herramientas. Si tuviera que aprender y memorizar una sintaxis para cada herramienta que usa y cada sitio que visita, pasaría todo su tiempo estudiando la documentación y los archivos de ayuda.

Es una buena idea ceñirse a los códigos HTTP estandarizados, teniendo esto en cuenta. Los códigos de error HTTP más comunes son:

  • 400 Solicitud incorrecta : la entrada falla la validación
  • 401 no autorizado : un usuario no está autorizado para acceder a un recurso
  • 403 Prohibido : el usuario está autenticado pero no tiene permiso para acceder a un recurso
  • 404 No encontrado : recurso no encontrado
  • 500 Error interno del servidor : un error genérico del servidor
  • 502 Bad Gateway : indica una respuesta no válida de otro servidor
  • ** Servicio 503 no disponible: sucedió algo inesperado en el lado del servidor

Permitir clasificación, filtrado y paginación

Las bases de datos con las que interactúan las API pueden volverse rápidamente bastante grandes y difíciles de manejar. Esto significa que corre el riesgo de abrumar su sistema si no tiene cuidado con las consultas de API. El filtrado es una forma de ordenar los resultados. La paginación también garantiza que los resultados que obtenga puedan devolverse unos pocos a la vez.

Esto también sirve como una importante protección contra fallas en el ecosistema de API. Las llamadas a la API a veces pueden costar dinero, lo que a menudo está determinado por el uso. ¡Imagínese lo que podría suceder si extrajera accidentalmente un Terabyte de datos en una sola solicitud!

Echemos un vistazo a cómo se vería eso en acción.

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

// employees data in a database
const employees = [
  { firstName: 'Jane', lastName: 'Smith', age: 20 },
  //...
  { firstName: 'John', lastName: 'Smith', age: 30 },
  { firstName: 'Mary', lastName: 'Green', age: 50 },
]

app.use(bodyParser.json());

app.get('/employees', (req, res) => {
  const { firstName, lastName, age } = req.query;
  let results = [...employees];
  if (firstName) {
    results = results.filter(r => r.firstName === firstName);
  }

  if (lastName) {
    results = results.filter(r => r.lastName === lastName);
  }

  if (age) {
    results = results.filter(r => +r.age === +age);
  }
  res.json(results);
});

app.listen(3000, () => console.log('server started'));

En este ejemplo, req.queryestablece los parámetros de consulta. Los valores individuales se desestructuran utilizando la sintaxis de desestructuración de JavaScript. Finalmente, el filtro se ejecuta en los resultados, que luego se devuelven.

Entonces, si tuviera que hacer una consulta /employees?lastName=Smith&age=30, devolvería:

[
    {
        "firstName": "John",
        "lastName": "Smith",
        "age": 30
    }
]

Esta cadena consulta la base de datos para devolver todos los empleados con el apellido de Smith que tienen 30 años de edad. La respuesta se devuelve con un objeto JSON.

También puede consultar una variedad de resultados. Los resultados también se pueden ordenar para que se muestren de diversas formas. Considere la siguiente cadena de consulta:

http://example.com/articles?sort=+author,-datepublished

Esto devuelve los resultados con los autores ascendentes y la fecha de publicación descendente.

Reflexiones finales sobre las API RESTful

La definición de Roy Fielding del estándar REST fue uno de los componentes clave que hizo posible la adopción generalizada de API en primer lugar. Como resultado, términos como API, REST y RESTful a menudo se usan indistintamente. La abundancia de jerga a veces puede dificultar el descifrado de la escritura técnica. Afortunadamente, recientemente publicamos un artículo sobre la diferencia entre REST y RESTful si está buscando una aclaración adicional.

Al igual que con cualquier cosa que tenga que ver con REST, estas son más pautas que reglas estrictas. Las API son infinitamente personalizables, por lo que ni siquiera el cielo es el límite. Solo estamos tratando de evitarle que llame accidentalmente a 6 mil millones de números de teléfono con una consulta accidental.

Dado que el uso y la configuración de API se reducen principalmente al gusto, también hay una variedad casi infinita de formas diferentes de optimizar sus API para lograr la máxima eficiencia. Puede echar un vistazo a algunos de nuestros otros tutoriales de API REST y las mejores prácticas de API para obtener aún más ideas sobre cómo aprovechar al máximo sus API.

Publicar un comentario

0 Comentarios