Header Ads Widget

Ticker

6/recent/ticker-posts

8 consejos para diseñar API REST de calidad

 Adriano Mota, arquitecto de soluciones de Ford Motor Company, comparte consejos bien elaborados para diseñar API de grado automotriz

Hay muchos aspectos importantes de la creación de API y servicios REST que los profesionales de API deben considerar. Por ejemplo, existen convenciones estándar de la industria sobre la estructuración de la URL para cada servicio, similares a los patrones utilizados para nombrar variables o clases de Java.

En este artículo, profundizaremos en ocho consejos de diseño inspirados en la guía de estilo interna que se utiliza para crear API sólidas en Ford . Desde comprender REST hasta aplicar los métodos HTTP correctos, el formato URI, el control de versiones y otras señales, le daremos al desarrollador de API promedio una excelente descripción general de cómo observar el estilo de API dentro de sus diseños.

Con estas mejores prácticas en mente, podrá diseñar API de alto rendimiento que los desarrolladores encontrarán fáciles de usar, ya que se ajustan a las convenciones de la industria.

1: Comprenda el estándar REST

En primer lugar, aunque existen otros estándares de API como SOAP, gRPC, GraphQL o Apache Kafka, Representational State Transfer o REST sigue siendo un estándar de diseño confiable para aplicar para desarrollar servicios de API web robustos. Al usar REST , debemos tener en cuenta los métodos HTTP, el formato JSON y los códigos de estado al diseñar nuestras API.

Dentro de los siguientes temas, intentaremos cubrir los principales aspectos a seguir cuando esté desarrollando sus API y Servicios REST.

Cuándo usar qué: REST, GraphQL, Webhooks y gRPC

2: Utilice el método HTTP correcto

En Ford, nos basamos en cuatro métodos HTTP para desarrollar nuestros servicios - GETPOSTDELETE, y PUTDe manera similar, estos cuatro métodos pueden cubrir la mayor parte de las operaciones para otros desarrolladores de API REST.

En la siguiente tabla, puede encontrar un mapeo de ellos y el propósito de cada uno. Hemos incluido un ejemplo de cómo cada método podría interactuar con un vehículo:

MÉTODO HTTPOPERACIÓN RELACIONADA CON CRUDEJEMPLO DE RUTADESCRIPCIÓNCOMENTARIO
OBTENERLeer/ vehículosObtener una lista de información de un determinado recurso (en este caso, vehículo).Si necesita obtener información específica del vehículo, debe usar obtener parámetros en el URI (ejemplo: / vehicle / {id}). Nunca use un JSON Body para solicitar información. Utilice siempre los parámetros GET en el URI.
ENVIARCrear/ vehículosPara crear un registro o tabla o información para el recurso.Si necesita obtener información específica del vehículo, debe usar obtener parámetros en el URI (ejemplo: / vehicle / {id}). Nunca use un JSON Body para solicitar información. Utilice siempre los parámetros GET en el URI.
ELIMINAREliminar/ vehículos / {id}Excluir de la base de datos la información de este recurso.Utilice siempre el parámetro get para identificar el recurso que se excluirá. Nunca use JSON Body para este tipo de solicitud.
PONERActualizar/ vehículos / {id}Actualizar información del recurso.Este es el único caso en el que podemos usar un parámetro GET, como un ID para identificar el recurso a actualizar, como un JSON Body con la información que se actualizará en la base de datos.

3: Sepa cómo definir recursos

Un recurso es la entidad con la que necesita trabajar (también conocido como dominio). Si su dominio es un vehículo , entonces debemos usar /vehiclesy señalar el recurso correcto para acceder en el URI.

Vea los ejemplos a continuación:

URLCOMENTARIO
http : // www veihclebrand prueba com api vehículosEn este ejemplo, debería poder usar el método GET HTTP para obtener una lista de vehículos
http : // www veihclebrand prueba com api vehicle / { code } / versionsPara este ejemplo, mediante el uso de un parámetro GET, solicite una lista de una versión de un código de vehículo específico.

Es bueno establecer convenciones de nomenclatura útiles para ayudar a estandarizar los URI. Por ejemplo, en Ford, los nombres de recursos / entidades de dominio deben establecerse en plural (en este ejemplo, "vehículos", no "vehículo"). Esta regla es aplicable para subniveles o sub-recursos.

4: Utilizar sub-recursos

En algunos casos, necesita un atributo específico para su recurso, pero el URI no es suficiente para representarlo. En estos casos, deberá trabajar con un subnivel, llamado sub-recursos para representar este atributo.

Por ejemplo, suponga que tiene el URI /api/vehicle, pero necesita recuperar información de piezas para este vehículo. En este caso, podemos crear un sub-recursos, y generar un URI como esto: /api/vehicle/{id}/parts.

Observe cómo hemos agregado el parámetro {id} para especificar de qué vehículo queremos recuperar la lista de piezas. Para las otras operaciones CRUD, el mapeo debería ser algo como esto:

MÉTODO HTTPOPERACIÓN RELACIONADA CON CRUDEJEMPLO DE RUTA
OBTENERLEER/ vehículos / {id} / parts
ENVIARCREAR/ vehículos / {id} / parts
ELIMINARELIMINAR/ vehículos / {id} / parts / {code}
PONERACTUALIZAR/ vehículos / {id} / parts / {code}

5: No utilice patrones de nombres de métodos Java

Las API tienen sus propios patrones que deben seguirse, por lo tanto, si usa URI similares a “/ vehículos / listParts” o “/ vehículos / getComboData” , tiene algo fuera de las convenciones mundiales para las API.

Los desarrolladores de API siempre deben usar recursos , sub-recursos y parámetros de consulta para formatear sus URI de API. Además, no se debe utilizar ningún otro patrón de otro lenguaje de objetos orientado. Siempre debemos utilizar los estándares REST.

Así, una estructura de URI para recuperar una lista de piezas de un vehículo específico, por ejemplo, sería /vehicles/{vin}/partsAlternativamente, si necesita cargar una lista para un cuadro combinado en su página HTML, el URI debería ser algo como /vehicles/orders/orders/vins.

Más sobre el diseño de API: los tres principios de un excelente diseño de API

6: Si actualiza su servicio REST, hágalo de manera constante

Cuando está evolucionando su servicio con el tiempo, una práctica es versionarlo . Todo el mundo sabe que siempre estamos mejorando nuestro código y, en algún momento, necesitamos refactorizarlo debido a cambios de alcance u otras razones.

Si está exponiendo API para socios externos, existe un riesgo potencial de romper el lado del cliente al actualizar su servicio, por lo que lanzar versiones completamente nuevas es una práctica para evitar algunos dolores de cabeza. ¿Pero cómo lo hago? Simple. En su API URI puede agregar la versión. Veamos un ejemplo.

Este URI significa que esta es mi primera versión expuesta de la API para obtener información de Vehículos. Puede devolver JSON con muchos datos en un formato específico. Sin embargo, como sabemos, el mundo no es perfecto y recibes un cambio de alcance, y necesitas mejorar tu código para actualizar el retorno de este servidor. ¿Cómo puedo hacerlo sin romper con clientes y clientes externos que ya lo están utilizando? Deberá crear una nueva versión de su servicio y convencer a los clientes de que lo adopten.http://www.site.teste.com/api/v1/vehicles/

Puede considerar usarlo como su nuevo servicio. En general, es una buena práctica documentar su API utilizando una de las muchas herramientas de documentación de OpenAPI . Con este enfoque, puede aumentar sus servicios, pero puede mantener a sus clientes anteriores compatibles con versiones anteriores de sus API.http://www.site.teste.com/api/v2/vehicles/

Sin embargo, preste atención. Si debe desarrollar continuamente nuevas versiones de su API, asegúrese de que su trabajo de diseño sea eficaz. Los cambios de alcance son aceptables hasta cierto punto, pero si tiene cinco versiones de su servicio, debe prestar más atención al definirlo.

7: JSON sobre XML para la mayoría de los casos

Dependiendo de su lenguaje de programación o el marco que esté utilizando para desarrollar su API, es posible devolver datos en JSON, XML u otros formatos también . Sin embargo, ¿hay algún formato estándar para usar?

En muchos sentidos, el formato JSON es el estándar para API y servicios REST . Sin embargo, si necesita devolver en XML , está permitido. Una vez más, debe verificar las especificaciones del ámbito de su negocio. Nosotros siempre recomendamos JSON para este enfoque, sobre todo para las interfaces de cara al público.

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

8: Devuelva el código de estado correcto

Desafortunadamente, no todas las API viven en un hermoso mundo de 200 códigos de estado HTTP. Si está realmente comprometido con el diseño de su API, prestará atención al código de estado correcto para devolver su servicio. Consulte la lista de códigos de estado a continuación y use el que se ajuste a sus necesidades. Estos códigos de estado enumerados son estándares HTTP , muy comúnmente utilizados para el diseño de API.

CATEGORÍACÓDIGO DE ESTADONOMBREDESCRIPCIÓN
EXITOSO200OkayEstado genérico de éxito. Se puede usar cuando el URI funciona bien y devuelve GETinformación correctamente.
EXITOSO201CREADOIndica cuándo se creó el recurso. Más utilizado como devolución POST.
EXITOSO202ACEPTADOSe utiliza cuando se aceptó la solicitud. Más utilizado en servicios asincrónicos.
EXITOSO204SIN CONTENIDOIndica que la URL funcionó bien, pero no hubo devolución para esta solicitud. Normalmente se utiliza para operaciones PUT y DELETE.
ERROR DE CLIENTE400Solicitud incorrectaEstado genérico de error. La mayoría acostumbrada a requisar con tipo de medio mal informado.
ERROR DE CLIENTE401No autorizadoEl servidor devuelve este estado cuando la solicitud falla debido a la falta de credenciales o la autorización falla.
ERROR DE CLIENTE403ProhibidoCuando su autorización funciona, pero sus credenciales no tienen autorización para acceder a este recurso. Ahí es cuando usamos este código.
ERROR DE CLIENTE404ExtraviadoLa URI informada no existe.
ERROR DE CLIENTE405Método no permitidoEl método HTTP utilizado para procesar este URI no es compatible. Por ejemplo, tu API solo funciona con GET, pero intentas PUT o POST. Este error debería plantearse.
ERROR DE CLIENTE412Fallo de condición previaAlgo en la solicitud no es coherente con lo que espera el servicio.
ERROR DE CLIENTE413Entidad demasiado grandeLa solicitud supera el límite que puede procesar el servidor.
ERROR DE CLIENTE415Tipo de papel no admitidoLa carga útil enviada al servicio no está en un formato que pueda reconocer. A veces se puede solucionar mediante el uso de atributos como Content-Type o Content-Encoding.
ERROR DE CLIENTE422Entidad sin procesarSe produjo un error semántico en su solicitud.
ERROR DE CLIENTE429Demasiadas solicitudesEl servidor está limitando sus solicitudes. Por alguna razón, alcanzó el límite de solicitudes para este servicio.
ERROR DEL SERVIDOR500error de servidor internoCuando una solicitud está bien, pero por alguna razón inesperada, el servidor no responde.
ERROR DEL SERVIDOR502Puerta de enlace incorrectaLa API no reconoce el error exacto informado por el Backend.
ERROR DEL SERVIDOR503Servicio no disponibleEl servidor no puede procesar la solicitud debido a una sobrecarga o mantenimiento.
Lea también: Mejores prácticas para el manejo de errores de API

¿Cómo aborda el estilo API?

En esta publicación, hemos cubierto los principios fundamentales para ayudar a los desarrolladores de API por primera vez a comprender los métodos HTTP, la construcción de URI, el control de versiones, los códigos de error y más. Los 8 sencillos consejos anteriores son simplemente imprescindibles para la construcción de API web.

Siguiendo las convenciones de estilo de calidad, puede mantener el ritmo de los desarrolladores ya acostumbrados a las API Web y el resto ful estándar. Por supuesto, una adopción REST completa incluiría hipermedia . Para una investigación más profunda de los estilos de API, los desarrolladores pueden leer detenidamente el API Style Book , una compilación de guías de estilo de diseño de API mantenidas por Arnaud Lauret.

Más allá de estos simples consejos, ciertamente hay muchas otras teorías sobre las soluciones de gestión o de gobierno para hacer cumplir ese estilo. Sin embargo, nos encantaría escuchar sus ideas. ¿Cómo está manejando su organización el estilo de API?

Publicar un comentario

0 Comentarios