Guía de la API v3 SUSE Rancher Prime anterior

La API v3 anterior tiene su propia interfaz de usuario accesible desde un navegador web. Esta es una forma fácil de ver recursos, realizar acciones y ver la curl equivalente o la solicitud y respuesta HTTP. Para acceder a ella:

Las solicitudes de API deben incluir información de autenticación. La autenticación se realiza con autenticación básica HTTP utilizando rancher-admin/users/settings/api-keys.adoc[claves de API]. Las claves de API pueden crear nuevos clústeres y tener acceso a múltiples clústeres a través de /v3/clusters/. Los roles de clúster y proyecto se aplican a estas claves y restringen qué clústeres y proyectos puede ver la cuenta y qué acciones puede realizar.

Por defecto, ciertos tokens de API a nivel de clúster se generan con un tiempo de vida infinito (ttl=0). En otras palabras, los tokens de API con ttl=0 nunca expiran a menos que los invalides. Para detalles sobre cómo invalidarlos, consulta la página de tokens de API.

La API es generalmente RESTful pero tiene varias características para hacer que la definición de todo sea descubrible por un cliente, de modo que se puedan escribir clientes genéricos en lugar de tener que escribir código específico para cada tipo de recurso. Para información detallada sobre la especificación de la API genérica, consulta la documentación adicional.

El diseño permite cargar solo la lista de esquemas y acceder a toda la información sobre la API. La interfaz de usuario de la API no contiene código específico de Rancher. La URL para obtener Esquemas se envía en cada respuesta HTTP como un encabezado X-Api-Schemas. Desde allí, puedes seguir el enlace collection en cada esquema para saber dónde listar recursos, y seguir otros links dentro de los recursos devueltos para obtener cualquier otra información.

En la práctica, puede que solo quieras construir cadenas de URL. Te sugerimos encarecidamente limitar esto al nivel superior para listar una colección (/v3/<type>) o obtener un recurso específico (/v3/<type>/<id>). Cualquier cosa más profunda que eso está sujeta a cambios en futuras versiones.

Los recursos tienen relaciones entre sí llamadas enlaces. Cada recurso incluye un mapa de links con el nombre del enlace y la URL donde puedes recuperar esa información. De nuevo, deberías GET el recurso y luego seguir la URL en el mapa links, no construir estas cadenas tú mismo.

La mayoría de los recursos tienen acciones, que hacen algo o cambian el estado del recurso. Para usarlas, envía un POST HTTP a la URL en el mapa de actions de la acción que deseas. Ciertas acciones requieren entrada o producen salida. Consulta la documentación individual para cada tipo o los esquemas para información específica.

Para editar un recurso, envía un HTTP PUT al enlace links.update en el recurso con los campos que deseas cambiar. Si falta el enlace, entonces no tienes permiso para actualizar el recurso. Los campos desconocidos y aquellos que no son editables se ignoran.

Para eliminar un recurso, envía un HTTP DELETE al enlace links.remove en el recurso. Si falta el enlace, entonces no tienes permiso para actualizar el recurso.

Para crear un nuevo recurso, envía un HTTP POST a la URL de la colección en el esquema (que es /v3/<type>).

La mayoría de las colecciones se pueden filtrar en el lado del servidor por campos comunes utilizando parámetros de consulta HTTP. El mapa filters te muestra qué campos se pueden filtrar y cuáles fueron los valores filtrados para la solicitud que realizaste. La interfaz de la API tiene controles para la configuración del filtrado y para mostrarte la solicitud apropiada. Para coincidencias simples de "igual", es solo field=value. Se pueden añadir modificadores al nombre del campo, por ejemplo, field_gt=42 para "el campo es mayor que 42." Consulta la especificación de la API para obtener todos los detalles.

La mayoría de las colecciones se pueden ordenar en el lado del servidor por campos comunes utilizando parámetros de consulta HTTP. El mapa sortLinks te muestra qué ordenamientos están disponibles, junto con la URL para obtener la colección ordenada por eso. También incluye información sobre el criterio de ordenación utilizado en la respuesta actual, si se especificó.

Las respuestas de la API están paginadas con un límite de 100 recursos por página por defecto. Esto se puede cambiar con el parámetro de consulta limit, hasta un máximo de 1000, por ejemplo, /v3/pods?limit=1000. El mapa pagination en las respuestas de colección te indica si tienes o no el conjunto completo de resultados y tiene un enlace a la siguiente página si no lo tienes.

Puedes usar las herramientas de desarrollador del navegador para capturar cómo se llama a la API v3. Por ejemplo, podrías seguir estos pasos para usar las herramientas de desarrollador de Chrome para obtener la llamada a la API para aprovisionar un clúster de distribución de Rancher Kubernetes: