Captura de pantalla 2016-06-05 a las 18.47.08

Siempre me ha gustado la documentación de WS2 (leído “güesos” para los amigos), el fabricante de Bus y API Gateway, en especial sus diagramas que encuentro tremendamente simples y autoexplicativos. Es por eso que no me he podido resistir a bajar su documento de buenas prácticas en servicios REST que puedes pedir aquí.

Antes de entrar en el contenido en sí del libro hay que recordar la definición de niveles de madurez de REST que puedes ver aquí, todo un must have que hay que tener cuenta cuando nos enfrentamos en el diseño de servicios REST. Esta clasificación del nivel de un API gateway nos ayuda a aprender el diseño del mismo y nos ayuda también a prevenir los errores más comunes en el diseño de servicios REST.

maturity

Sobre el documento de WS2, un poco largo, no todo es correcto a mi modo de ver. Me llama la atención la fijación que tienen sobre el data model, el que hay detrás del API. Y es que parece que consideran que el objetivo de todo API es acceder a un modelo de datos. ¿Dónde se quedó la orientación a objetos y la caja negra que todo servicio debe ser?. En mi opinión el modelo de datos es algo que debe permanecer oculto para el consumidor del API. Yo lo consideraría más bien como diagrama de clases.

Resource URIs

Especialmente importante es el apartado 5, sobre el diseño de las URIs de los recursos, que inexplicablemente parece que no se sigue demasiado.

{scheme}://{host}/{base-path}/{path}[?{query-string}]

Usa la barra “/” para indicar la relación jerárquica entre recursos. El nombre del padre debe preceder el nombre de sus hijos inmediatos.

El path base

/{feature-code}/[ {sub-code}/ ]/{version}

Propone la siguiente estructura para definir la base del path de la URI, agrupando los servicios por funcionalidad o feature. Dejando espacio también para una substructura (sub-code) si necesitamos hacer una subdivisión de los servicios por grupos de funcionalidad.

La versión del API es parte de su URI

Un documento útil y completo

También se trata el uso de los verbos de HTTP, las cabeceras de entrada y de respuesta y como no, lo que considero mi preferido, los códigos de status. ¿Por qué no se usan estos códigos en las APIs que veo en el día a día? es uno de esos misterios de la vida.

Temas como el filtro en las búsquedas, la paginación y el cacheo en la parte cliente también tienen cabida en este documento de buenas prácticas, sin olvidarse de la seguridad y de como reportar de errores.

Evidentemente no se puede estar al 100% de acuerdo con el documento pero casi. Una lectura muy recomendada si se quiere saber cómo diseñar servicios REST.

 

Anuncios