Saltar al contenido principal

2.1-Naming-APIs

Ver en Git

Generalidades

Las URLs deben estar en inglés

Las URLs de las APIs tienen 2 grandes partes:

  1. La parte inicial de la URL de una API corresponde al micro-servicio. Esto debe ser único a nivel plataforma y esta asociado directamente al balanceador de carga o API gateway para enrutar el tráfico. Antes de comenzar un nuevo microservicio se debe validar a nivel balanceador que la primera parte de la URL sea conveniente. Por otra parte en un microservicio debemos respetar ese "preambulo" para todas las APIs. En algunos casos puede suceder que un microservicio tenga asociados varios de esos "preambulos"

  2. La parte final de la URL es la que define la api en cuestion, en este caso el developer tiene libertad para poner los nombres. Tener en cuenta seguir una taxonomía lógica y seguir los lineamientos REST

Ejemplo:

<dominio.com>/api/fields/field/boundary

En este caso "/api/fields" es loque define el microservicio. El balanceador de carga va a definir el contenedor al cual enviar el tráfico en base a ese preambulo

Por otra parte "/field/boundary" es un endpoint específico que por el nombre evidentemente devuelve el boundary de un field.

Versioning

El versionado simplemente será implementado agregando un "/v2", "/v3" ... "vN" en la url de la API, pero en la sección final, nunca en la parte del "preambulo" que es la que corresponde al microservicio y al balanceador de carga.

Ejemplo:

Api original: <dominio.com>/api/fields/field/boundary Versionado de todo el servicio: <dominio.com>/api/fields/v2/field/boundary Versionado del conjunto de apis field y sus descendientes unicamente: <dominio.com>/api/fields/field/v2/boundary Versionado de la api boundary unicamente: <dominio.com>/api/fields/field/boundary/v2