Manual de desarrolladores de aplicaciones

Autenticación de API

Al escribir una aplicación que realiza llamadas de API a Learning Manager, debe registrarla mediante la aplicación del administrador de integración.

Las API de Learning Manager utilizan el marco de OAuth 2.0 para autenticar y autorizar las aplicaciones cliente.

Procedimiento

1. Configurar la aplicación

Puede configurar la aplicación con el ID y el secreto de cliente para utilizar los puntos finales adecuados. Una vez registrada la aplicación, puede obtener el ID y el secreto de cliente. Se debe utilizar "Get URL" en el navegador, ya que autentica a los usuarios de Learning Manager mediante sus cuentas preconfiguradas, como SSO, Adobe ID, etc.

Una vez completada correctamente la autenticación, el navegador redirige al URI de redirección indicado en la URL anterior. Se añade el parámetro code junto al URI de redirección.

2. Obtener token de actualización del código

POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

Cuerpo de la solicitud POST:

3. Obtener un token de acceso del token de actualización

URL para obtener el token de acceso:

POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

Cuerpo de la solicitud POST:

URL para verificar los detalles del token de acceso

GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>

Limitación de uso

Un token de acceso es válido durante siete días. Después de un día, debe generar un nuevo token de acceso mediante el token de actualización. Si genera un nuevo token de acceso a partir del token de actualización mientras un token de acceso existente sigue siendo válido, se devuelve el token existente.

A continuación, se describen algunos de los términos más utilizados en la API de Learning Manager como referencia.

Includes

Los desarrolladores pueden acceder a un único modelo de objetos de API y también a varios modelos asociados a ese modelo. Para acceder a los modelos relacionados posteriores, debe conocer la relación de cada modelo con otros modelos. El parámetro Includes permite a los desarrolladores acceder a los modelos dependientes. Puede utilizar un separador de comas para acceder a varios modelos. Para obtener ejemplos de uso y más detalles sobre includes, consulte la sección de modelos de API de ejemplo en esta página.

Solicitud de API

Las solicitudes de API se pueden realizar mediante una solicitud HTTP. En función del punto final y el método, el desarrollador puede elegir entre diversos verbos de HTTP, como GET, PUT, POST, DELETE, PATCH, etc. En algunas solicitudes, se pueden transferir parámetros de consulta. Al realizar una solicitud de un modelo de datos específico, el usuario también puede solicitar modelos relacionados, tal y como se describe en las especificaciones de la API JSON. La estructura de una solicitud API típica se describe en el uso del modelo de ejemplo.

Respuesta de API

Si un cliente realiza una solicitud de API, se obtiene un documento JSON según la especificación de API JSON. La respuesta también contiene el código de estado HTTP, que el desarrollador puede comprobar para realizar los pasos siguientes adecuados en la lógica de la aplicación. La estructura de una respuesta de API típica se describe en uso del modelo de ejemplo.

Errores

Cuando falla una solicitud de API, se obtiene una respuesta de error. El código de estado HTTP devuelto en la respuesta indica la naturaleza del error. Los códigos de error se representan con números para cada modelo en la referencia de API. 200, 204, 400 y 404 son algunos de los errores comunes representados en las API que indican problemas de acceso HTTP.

Fields

Los atributos del objeto de API y sus relaciones se denominan de forma conjunta "Fields". Consulte la API JSON para obtener más información. Puede utilizar Fields como parámetro al realizar llamadas de API para obtener uno o más atributos específicos del modelo. Si no se utiliza el parámetro "Fields", la llamada de API obtiene todos los atributos disponibles del modelo. Por ejemplo, en la siguiente llamada de API, fields[skill]=name obtiene únicamente el atributo name del modelo de aptitud.

https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name

Paginación

A veces, una solicitud de API proporciona una larga lista de objetos en la respuesta. En esos casos, el atributo de paginación permite al desarrollador obtener los resultados secuencialmente en varias páginas, en las que cada página contiene un intervalo de registros. Por ejemplo, el atributo de paginación en Learning Manager permite establecer el número máximo de registros que se mostrarán en una página. Además, puede definir el valor del intervalo de registros que se mostrarán en la página.

Ordenación

Se permite la ordenación en los modelos de API. En función del modelo, elija el tipo de ordenación que se aplicará a los resultados. La ordenación se puede aplicar en orden ascendente o descendente. Por ejemplo, si especifica code sort=name, se trata de una ordenación ascendente por nombre. Si especifica code sort=-name, se trata de una ordenación descendente por nombre. Consulte la especificación de API JSON para obtener más información.

Ilustración de uso de API

Supongamos que un desarrollador desea obtener el nombre de la aptitud, la cantidad máxima de puntos asignada al nivel de aptitud y los puntos obtenidos por el alumno para esa aptitud.

Un modelo "userSkill" de las API de Learning Manager consta de los atributos predeterminados: id, type, dateAchived, dateCreated y pointsEarned. Por lo tanto, cuando un desarrollador utiliza el método GET para adquirir información del modelo "userSkill", los datos actuales relativos a los atributos predeterminados se muestran en la salida de respuesta.

Sin embargo, en este caso, el desarrollador desea obtener el nombre de la aptitud y los puntos de nivel de aptitud del usuario. La API de Learning Manager permite acceder a esta información relacionada mediante campos de relación y parámetros "include". Los modelos asociados de "userSkill" se obtienen en la etiqueta de relaciones. Puede obtener información de cada uno de los modelos asociados llamándolos junto con el modelo "userSkill". Para obtener esta información, utilice el parámetro code include con valores separados por puntos para cada uno de los modelos asociados. Puede utilizar la coma como separador para solicitar otro modelo, como user include=skillLevel.skill,course

Llamada de API

https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned

Por ejemplo, "userId" puede ser 746783 y "userSkills id" puede ser 746783_4426_1.

Respuesta de llamada de API