Introducción a Cloud API

Nota: Si ya es usuario de Caseware Cloud API y ha implementado la V1, planifique su transición a la V2. Si eres un usuario nuevo, asegúrate de empezar por la V2. Todos los ejemplos son de V2.

Caseware Cloud API proporciona un conjunto de operaciones de API para automatizar la gestión de los datos de su consulta, como clientes, usuarios, grupos, permisos y mucho más.

La aplicación SDK ejemplifica lo siguiente:

  • Puntos finales disponibles y operaciones en cada punto final

  • Parámetros de entrada y salida para cada operación

  • Encabezados obligatorios y de respuesta

Autenticación y autorización

Al registrar un cliente de API y adquirir un token de API, puede enviar solicitudes a los puntos finales de Cloud API. La API de Caseware Cloud está estructurada en torno a REST. Las URL predecibles orientadas a recursos ofrecen respuestas codificadas en JSON, junto con códigos de respuesta HTTP estándar.

Cloud API sigue los requisitos de autenticación del flujo de concesión de credenciales de cliente del protocolo OAuth 2.0. Este flujo está diseñado para la comunicación confidencial de servidor a servidor sin usuario final.

Procedimientos iniciales

  1. Obtener un ID de cliente y un secreto de cliente. Para más información, véase Ajustes de la empresa - Integración .

  2. A continuación, utilice el ID de cliente y el secreto de cliente generados para obtener un token de API en POST /auth/token:

requests 

curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/auth/token' \ --header 'accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "ClientId": "966592b3-8586-4541-9909-f7a901ef0b9a", "ClientSecret": "sg1eb53tkbn6dez0momdxr0gm87fih1kkoekm40u", "Language": "en" }'

Respuesta

Código de estado: 200 OK 

              { "Token": "YTA1NGNiOTgtOWJjOS02NDg5LWIyYTgtZTZhNDA5MDJiNGQwOjk1Y2U2YmRjLWUzMDktMmxZS00ZDYyLWY5NWJmZGE4MGY1ZjpiYTk4OTc1YS04Mjc4LTRhZWEtOWVjOC0wMDcyM2FhMjRjNGY=" }

Utilice el token de API como token portador en una cabecera de autorización para realizar solicitudes de API adicionales. El token de la API es válido durante 30 minutos.

Duración de la sesión

Cada autenticación de Cloud API genera una nueva sesión que dura 30 minutos y que no invalida ninguna sesión anterior. Un restablecimiento del secreto de cliente invalida todas las sesiones existentes de ese cliente API. En consecuencia, se requiere una nueva autorización.

Política de limitación de tipos

El límite de velocidad tiene como objetivo evitar que los recursos de la API de la nube se agoten. Cuando un cliente de la API realiza una solicitud, la disponibilidad de los recursos disminuye temporalmente y se repone tras un cierto retraso.

Cuando no hay recursos disponibles, se devuelve el estado HTTP 429 (demasiadas solicitudes). Puede utilizar la cabecera de respuesta ratelimit para determinar el número restante de solicitudes, la capacidad de ráfagas, la tasa de reposición y el número de fichas solicitadas. El algoritmo token bucket regula las solicitudes entrantes. Imagina un cubo de fichas. Cuando se realiza una solicitud a la API, debe tomarse un token del bucket para seguir procesando la solicitud. La solicitud API se rechaza si no hay ningún token disponible en el bucket. Los tokens se añaden automáticamente al cubo al ritmo de reposición a medida que las solicitudes de la API consumen tokens de la reserva disponible.

Encabezados de respuesta

Encabezado Descripción
x-ratelimit-burst-capacity El número máximo de fichas que puede contener el cubo y que pueden utilizarse en un segundo.
x-ratelimit-remaining The number of tokens left in the bucket.
x-ratelimit-replenish-rate Número de fichas que se reponen en un segundo.
x-ratelimit-requested-tokens El número de tokens que cuesta una solicitud API.

Nota: Es probable que cambien los valores de la configuración del límite de velocidad. No codifique estos valores.

View API documentation

El punto final y los parámetros de Cloud API se describen en la aplicación Caseware Cloud SDK:

Para ver la compatibilidad con API:

  1. En su navegador, vaya a esta URL:
https://<region>.casewarecloud.com/<firm>/sdk

 

  1. A la izquierda, expanda /caseware-cloud
  2. Seleccione la versión que está utilizando.
  3. Utilice la Búsqueda para localizar la operación que necesita:

Utilizar la búsqueda para encontrar una operación API

Se describen los parámetros de consulta que pueden utilizarse en la API de su solicitud.

Consulte el formato de la URL de la solicitud ampliando el desplegable de la firma del endpoint:

Ver el formato de la URL de solicitud

  1. Consulte los ejemplos de respuesta de la derecha para ver listados y descripciones de los datos que puede esperar en la respuesta.

View response samples for an API request