Inicio rápido: Emisión de insignias abiertas con la API de insignias digitales de Parchment
Aquí encontrará ejemplos guiados que le mostrarán cómo usar la API de insignias digitales de Parchment, cómo autenticarse, crear un emisor, definir una clase de insignia y emitir una aserción. Hay muchas más cosas que puede hacer con la API de insignias digitales de Parchment. Consulte la documentación completa de la API de insignias digitales de Parchment (región de EE. UU.) para obtener una lista de los puntos de conexión.
Entornos regionales
Ofrecemos soporte para servidores en diversas regiones, además de un servidor de pruebas. El dominio de la interfaz de usuario y el dominio de la API varían según el servidor que utilice. Consulte los dominios para los entornos de Parchment Digital Badges en todo el mundo. En nuestra documentación, utilizamos el dominio de EE. UU. por defecto; asegúrese de sustituirlo por el dominio correcto si no utiliza los servidores de producción de EE. UU.
Autenticación
Parchment Digital Badges utiliza OAuth2 para la mayoría de sus operaciones. Como usuario de la API, puede obtener un token de portador OAuth2 para su cuenta de usuario de Parchment Digital Badges mediante una concesión basada en contraseña, o bien, puede obtener tokens de autenticación para varios usuarios registrando su propia aplicación conectada. Para obtener más información sobre cómo registrar una clave y un secreto de aplicación, consulte aquí .
Obtención de un token
Esta guía se centra en comenzar rápidamente, por lo que utilizaremos una concesión basada en contraseña en el servicio gratuito de Parchment Digital Badges, con sede en EE. UU., o bien, una región diferente, como se describe anteriormente. Solicite la autenticación mediante una solicitud POST a https://api.badgr.io/o/token con su dirección de correo electrónico y contraseña como parámetros de solicitud de nombre de usuario y contraseña . Esta solicitud puede realizarse con un cuerpo de solicitud JSON, datos de formulario o x-www-form-urlencoded.
Por ejemplo, desde cURL: curl -X POST ' https://api.badgr.io/o/token' -d "username=TUCORREOELECTRÓNICO&password=TUCONTRASEÑA"
Recibirás un documento como respuesta, similar al siguiente:
{
"access_token": "YOURACCESSTOKEN",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "YOURREFRESHTOKEN",
}
¿No tienes contraseña en tu cuenta? Para usar la concesión de permisos basada en contraseña, necesitas establecer una contraseña en tu cuenta. Es posible que aún no tengas una si creaste tu cuenta iniciando sesión desde un proveedor de identidad externo, como Facebook o Google. Puedes agregar una contraseña una vez que hayas iniciado sesión desde tu página de perfil. Si aún no tienes una cuenta, regístrate gratis aquí . Necesitarás una dirección de correo electrónico verificada para acceder a las siguientes API, así que asegúrate de completar ese paso.
Autenticación de solicitudes con un token Bearer de OAuth2
Agregue un encabezado de autorización a cada una de las solicitudes API subsiguientes con un valor de Bearer YOURACCESSTOKEN (reemplazando YOURACCESSTOKEN con el valor de la clave access_token en la respuesta anterior).
Puedes usar este token para solicitar cualquier API a la que tu usuario tenga acceso (el "ámbito" predeterminado que obtuviste anteriormente era muy permisivo: rw:profile rw:issuer rw:backpack , por lo que se puede usar para realizar cualquiera de las llamadas a la API que tu usuario necesite hacer).
Por ejemplo, en una solicitud para recuperar el perfil del usuario realizada con cURL, este encabezado se configuraría de la siguiente manera: curl ' https://api.badgr.io/v2/users/self' -H "Authorization: Bearer YOURACCESSTOKEN"
Sobre de respuesta
Todas las respuestas de la API de insignias digitales Parchment V2 que tienen un cuerpo envuelven dicho cuerpo en un sobre de respuesta JSON que proporciona los datos resultantes de la solicitud, así como metadatos sobre el éxito o el fracaso de la misma. El resultado siempre es una lista ([]), incluso cuando solo hay una entidad o ninguna entidad en el resultado.
Un ejemplo de cuerpo de respuesta exitoso:
{ "estado": { "descripción": "ok", "éxito": verdadero }, "resultado": [ { "identidad": "g66EErPYSZOyssbD79U3zB" } ]}
Cada una de las entidades de los siguientes ejemplos, una vez creadas correctamente, tendrá una propiedad entityId que se utilizará para identificarla en las llamadas posteriores a la API (normalmente en la ruta de la solicitud al crear o ver entidades relacionadas).
Un ejemplo de cuerpo de respuesta fallida:
{ "estado": { "descripción": "solicitud incorrecta", "éxito": false }, "resultado": [], "errores de validación": ["Aquí aparecen los errores a nivel de formulario (que afectan a varios campos)."], "errores de campo": { "nombre": ["Este campo es obligatorio."] }}
Las propiedades validationErrors y fieldErrors solo aparecen en el documento cuando status.success es falso.
API del emisor
Algunas de las llamadas a la API más importantes que los clientes realizan a la API de Parchment Digital Badges son para emitir insignias. Emitirlas manualmente a través de la interfaz web es una buena opción, pero para escalar sus programas de emisión de insignias, debe comenzar a automatizar el proceso, y la API de Parchment Digital Badges lo facilita. Cada insignia es otorgada por un emisor, por lo que comenzaremos creando un perfil de emisor, luego definiremos la clase de insignia que se otorgará y, finalmente, otorgaremos una aserción de esa clase de insignia.
Cada una de las tres solicitudes que comenzaremos en esta sección es una solicitud POST. Recomendamos usar la API en formato JSON tanto para el Content-Type del cuerpo de la solicitud como para el contenido del cuerpo de la respuesta. Por defecto, si no se especifica el encabezado Accept: application/json , se devolverá JSON.
Crear perfil de emisor
Ruta de solicitud : /v2/issuers
Un perfil de emisor describe a una organización o persona que otorga insignias abiertas. Se publica como la clase Perfil de insignias abiertas https://openbadgespec.org/#Profile .
Propiedades:
- Se requiere el nombre : cadena de caracteres.
- Se requiere una descripción : cadena de caracteres.
- Se requiere una URL . Debe ser la URL completa de una página que describa a este emisor/programa.
- La imagen es opcional, debe ser una cadena codificada en base64 y solo puede ser PNG o SVG. Por ejemplo, un archivo de imagen PNG pequeño debería aparecer así en los cuerpos de las solicitudes que requieren un campo de imagen: "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
- El correo electrónico debe ser una dirección verificada en la cuenta de Insignias Digitales Parchment del usuario que se autentica. Acceda a /v2/users/self para recuperar su perfil y ver sus direcciones de correo electrónico verificadas.
Definir BadgeClass
Ruta de solicitud : /v2/issuers/ :issuer_entity_id /badgeclasses Una BadgeClass es un tipo de insignia que un emisor puede otorgar repetidamente (creando muchas aserciones de esa BadgeClass, cada una para un destinatario diferente). Consulte la especificación de insignias abiertas: BadgeClass https://openbadgespec.org/#BadgeClass
Propiedades:
- Se requiere el nombre : cadena de caracteres.
- Se requiere una descripción : cadena de caracteres.
- Se requiere una imagen y solo puede estar en formato PNG o SVG. Por ejemplo, un archivo de imagen PNG pequeño debería aparecer así en los cuerpos de las solicitudes que requieren un campo de imagen: "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
- Se requieren criterios. Se debe proporcionar uno o ambos de los siguientes elementos : criteriaNarrative (una cadena con formato Markdown) y/o criteriaUrl (una URL completa de una página que represente los criterios para esta insignia).
- tags es opcional. Si está presente, debe ser una lista ([]) de una o más cadenas;
- La alineación es opcional. Si está presente, debe ser una lista ([]) de uno o más objetos JSON que tengan cada uno de estas propiedades:
- targetName requerido, cadena
- targetUrl (obligatorio), cadena de URL completa
- targetDescription opcional, cadena
- targetFramework ( opcional, cadena de texto) (¿a qué marco de competencias pertenece este objetivo de alineación?)
- targetCode ( opcional, cadena de texto) (¿Existe alguna subetiqueta dentro de targetUrl que la distinga de otros posibles destinos que se identificarían con la misma URL? Úsela solo si targetUrl resultara ambigua).
Afirmación del problema
Ruta de solicitud : /v2/badgeclasses/ :badgeclass_entity_id /assertions
Una Aserción es una instancia de una BadgeClass (tipo de logro reconocido por un Emisor) que se otorga a un destinatario. Puede haber varias Aserciones de una BadgeClass específica que un Emisor haya otorgado a diferentes destinatarios. Consulte la Especificación de Insignias Abiertas: Aserción https://openbadgespec.org/#Assertion
Propiedades:
- El destinatario es obligatorio (la única propiedad obligatoria) y debe ser un objeto JSON con al menos una clave de identidad . Otras propiedades opcionales del "IdentityObject" del destinatario incluyen: tipo (¿qué tipo de identificador es la identidad ? Elija entre correo electrónico , teléfono y URL ); y hash (booleano, ¿debe la identidad ser hasheada en la aserción final de Open Badges?). Cuando obtiene el objeto de la API, plaintextIdentity , aparece una propiedad de solo lectura para mostrarle cuál era su valor de identidad original en caso de que esté oculto detrás del hash público (cuando hashed == true ).
- La evidencia puede expresarse en términos de una “narrativa” general y/o uno o más “elementos de evidencia”. `narrativa` es una propiedad opcional que acepta cadenas con formato Markdown. `evidencia` es una propiedad que acepta una lista ([]) de objetos JSON ({}) que contienen una narrativa y/o un ID (que es una URL a un elemento de evidencia alojado en HTTP).
- Tenga en cuenta que la imagen es de solo lectura en este punto final. La imagen "preparada" será generada por el servidor a partir de la imagen BadgeClass.
- El parámetro `issuedOn` es opcional: puede reemplazar la fecha de emisión con una fecha anterior. Se espera una marca de tiempo con formato ISO 8601 que incluya el identificador de zona horaria. Por ejemplo: ` 2018-11-26T13:45:00Z` (en este caso, la "Z" significa "Zulu", UTC).
- expires es una fecha de vencimiento opcional para la Aserción. Se esperan las mismas expectativas de formato que issuedOn .
- `notify` es una propiedad booleana opcional. ¿Debe notificarse al destinatario por correo electrónico? (Solo funciona con el tipo de destinatario de correo electrónico ). Nota: para cumplir con las divulgaciones de privacidad requeridas, se enviará una notificación por correo electrónico al destinatario tras la primera entrega de cada insignia digital en un servidor específico de Parchment Digital Badges.
Enlaces útiles