java - restful - ¿Es mejor colocar una API REST en un subdominio o en una subcarpeta?

rest routes best practices

Question

Tenemos una aplicación web que está alojada con la URL http://example.com . Ahora queremos extender una parte de esta aplicación como un servicio de descanso, y estamos debatiendo sobre el mejor patrón de URL. Busqué, pero no pude encontrar ninguna orientación concreta.

¿Deberíamos tener el patrón de URL http://api.example.com o http://exaple.com/api/v1 ?

¿Hay alguna guía estándar para esto?

Answer 1

Creo que deberías considerar usar ni http://api.example.com ni http://example.com/api/v1 .

En su lugar, sugeriría usar http://example.com/api y la negociación de contenido para las versiones.

Aquí están mis pensamientos por qué:

Usando un subdominio:

De acuerdo con la Especificación del esquema de URI , está definiendo la API en la parte de autoridad de la URI, que se utiliza para definir su host, en lugar de definir una aplicación o API en su host. En realidad, está creando una dirección diferente para su API, lo que significa que la autenticación podría no funcionar para api.example.com como lo hace para example.com.

Una razón válida para hacer esto podría ser cuando se diseña una nueva instancia para dispositivos móviles, por ejemplo, mobile.example.com, pero considero que esto es más una decisión de infraestructura y no una funcional.

Usando una ruta no versionada en el dominio principal:

Hay dos bits de información aquí: uno es una indicación de que hay un recurso de API y el segundo es que existe el número de versión de ese recurso de API (v1).

No hay nada malo en usar /api/ para hacer una distinción entre la API y, por ejemplo, su vista web que podría ejecutarse en /web/ . Esto puede considerarse la mejor práctica común.

No estoy seguro de si pretendía esto, pero su pregunta incluye una consulta sobre cómo resolver las versiones de API. Personalmente, creo que el control de versiones de la API no debe hacerse usando URL, ya que están destinadas a permanecer estables el mayor tiempo posible. Cool URIs no cambian! En su lugar, considere usar la información de tipo de contenido HTTP para la versión de su API. Realmente encontré este método usado en la documentación de VMware . Además, aquí hay una publicación bastante antigua, pero aún útil, sobre el tipo de contenido de Peter Williams .

Answer 2

Depende de tus necesidades.

Si usas http://api.example.com , tu API se convertirá en un subdominio. Básicamente, este patrón de URL es bueno si su servicio REST debe ser consumido por varios clientes, pero si solo hay un cliente conectado a su API, el patrón http://example.com/api/v1 es bueno. Sin embargo, si desea agregar más API con más clientes conectados, es mejor usar http://example.com/api/v1 . Por ejemplo, considere lo siguiente.

http://example.com/reportapi/apioperation?parameters
http://example.com/paymentapi/apioperation?parameters
http://example.com/searchapi/apioperation?parameters

Por último, pero no menos importante, PayPal utiliza el patrón http://example.com/api/v1 .

Answer 3

Este es un caso de compensaciones, sin la mejor solución.

Por ejemplo, si su http://example.com/ proporciona contenido a través de una interfaz web estándar así como a través de la API, entonces necesita algo como http://api.example.com/api/<version>/<the usual resource pattern> solo para separar el acceso a la aplicación basada en navegador de la interacción API. ¿Esto tiene sentido?

Ejemplo: api.rottentomatoes.com

Sin embargo, incluso si su dominio está dedicado a las llamadas a la API, es significativo usar el patrón anterior de todos modos, y reserve http://example.com/ para otras formas de interactuar con su aplicación. Por ejemplo, puede querer http://example.com/mobile/ , etc.