Resolver locale, plataforma y tema de Docs
Referencia para operadores sobre cómo las peticiones a la API de Docs normalizan locale, plataforma, dispositivo, tema y las entradas de búsqueda de la API antes de devolver una respuesta de índice o de artículo.
En este artículo
Usa esta guía cuando necesites confirmar cómo se interpretará una petición de índice o de artículo de Docs antes de que Antylogic devuelva contenido de documentación.
Las rutas públicas y autenticadas de Docs comparten el mismo resolutor y el mismo bundle de contenido. El prefijo de ruta controla la autenticación; los parámetros de consulta controlan el idioma, la familia de dispositivo, el tema de la media y la búsqueda del lado de la API.
Antes de empezar
- La petición apunta a una ruta que no es de assets bajo /api/public/docs o /api/app/docs.
- Para peticiones GET, el bundle de contenido de Docs está disponible desde DOCS_CONTENT_PATH o desde la ruta de contenido de docs por defecto del backend.
- Para /api/app/docs, el usuario demo u otro usuario de la app ya está autenticado a través del middleware de la API de la app.
- Las entradas opcionales pueden suministrarse como locale, platform, device, theme, q o la cabecera Accept-Language.
Instrucciones
- 1.
Elige la ruta de Docs
Usa /api/public/docs para respuestas de documentación sin autenticación. Usa /api/app/docs desde una sesión autenticada de la app. Ambos prefijos llaman al mismo resolutor de opciones después de superar las comprobaciones de ruta, método, assets y bundle de contenido.
- 2.
Resuelve el idioma
Pasa locale cuando el cliente necesite un idioma concreto de Docs. locale tiene prioridad sobre Accept-Language; es-ES resuelve a es. Si no se suministra ningún idioma soportado, el backend cae a es.
- 3.
Resuelve la plataforma o el dispositivo
Pasa platform cuando el cliente ya conozca el formato de destino. Si platform está en blanco, se usa device en su lugar. iphone, ios, android, phone, mobile, movil y móvil resuelven a la plataforma de API mobile y a la plataforma interna de media iphone. desktop resuelve a web.
- 4.
Resuelve el tema
Pasa theme=dark solo cuando deba preferirse la media de documentación en oscuro. Cualquier tema en blanco o no soportado resuelve a light. Las respuestas de índice no devuelven theme; las respuestas de detalle de artículo sí.
- 5.
Usa la búsqueda de la API de forma deliberada
Usa q solo en rutas de índice cuando un consumidor de la API necesite filtrado en el servidor, por ejemplo q=reservas. Las cajas de búsqueda visibles de Docs en la app nativa y en la landing filtran localmente el índice ya cargado, así que no deben documentarse como si enviasen q a /api/app/docs.
- 6.
Lee la respuesta devuelta
En las respuestas de índice, confirma locale, platform, article_count, sections y query opcional. En las respuestas de artículo, confirma locale, platform, theme y los campos de resolución de media como resolved_platform o resolved_theme cuando haya media.
Validaciones y límites
- Solo se aceptan GET y HEAD en las rutas de Docs que no son de assets; el resto de métodos devuelven 405 antes de la resolución de opciones.
- Las comprobaciones HEAD que no son de assets y las peticiones /assets/... se gestionan antes de resolver las opciones.
- Los valores no soportados de locale, platform, device y theme se canonizan a valores por defecto en lugar de rechazarse.
- El normalizador de locale del backend solo implementa en y es; el valor por defecto del backend es es.
- Solo mobile, tablet y web se representan en las respuestas de plataforma de la API; la selección interna de media usa iphone, ipad o web.
- q solo se recorta. Un q en blanco se omite del JSON, y q en rutas de detalle de artículo lo almacena el resolutor pero no lo usa la búsqueda de artículo.
- Las rutas públicas de Docs no requieren autenticación. Las rutas autenticadas de Docs de la app requieren un bearer token o una cookie access_token y se bloquean para cuentas pendientes de eliminación.
Resultado esperado
Los operadores pueden predecir y verificar los campos normalizados de la respuesta de Docs para peticiones públicas y autenticadas sin confundir el filtrado q del lado de la API con la búsqueda local visible de las pantallas de Docs.