Guia rápido: Emitindo Open Badges com a API de Badges Digitais da Parchment
Aqui estão alguns exemplos guiados que mostram como usar a API de Distintivos Digitais do Parchment, incluindo autenticação, criação de um Emissor, definição de uma Classe de Distintivo e emissão de uma Asserção. Há muitas outras funcionalidades disponíveis na API de Distintivos Digitais do Parchment. Consulte a documentação completa da API de Distintivos Digitais do Parchment (região dos EUA) para obter uma lista de endpoints.
Ambientes regionais
Oferecemos suporte a servidores em diversas regiões, além de um servidor de testes. O domínio da interface do usuário e o domínio da API variam de acordo com o servidor que você está utilizando. Consulte os domínios para os ambientes do Parchment Digital Badges em todo o mundo. Utilizamos o domínio dos EUA como padrão em nossa documentação; portanto, certifique-se de substituir o domínio correto caso não esteja utilizando os servidores de produção dos EUA.
Autenticação
A Parchment Digital Badges utiliza o OAuth2 para a maioria das operações. Como usuário cliente da API, você pode obter um token Bearer OAuth2 em nome da sua própria conta de usuário da Parchment Digital Badges por meio de uma concessão baseada em senha, ou pode obter esses tokens de autenticação em nome de vários usuários registrando seu próprio aplicativo conectado. Saiba mais sobre como registrar uma chave e um segredo de aplicativo aqui .
Obtenção de um Token
Este guia se concentrará em como começar rapidamente, portanto, usaremos uma concessão baseada em senha no serviço gratuito hospedado nos EUA da Parchment Digital Badges ou usaremos uma região diferente, conforme descrito acima. Solicite a autenticação fazendo uma solicitação POST para https://api.badgr.io/o/token com seu endereço de e-mail e senha como parâmetros de solicitação de nome de usuário e senha . Esta solicitação pode ser feita com um corpo de solicitação JSON, dados de formulário ou x-www-form-urlencoded.
Por exemplo, usando cURL: curl -X POST ' https://api.badgr.io/o/token' -d "username=SEUEMAIL&password=SUASENHA"
Você receberá um documento em resposta semelhante ao seguinte:
{
"access_token": "YOURACCESSTOKEN",
"token_type": "Bearer",
"expires_in": 86400,
"refresh_token": "YOURREFRESHTOKEN",
}
Não tem uma senha na sua conta? Para usar o recurso de permissão por senha, você precisa definir uma senha para a sua conta. Pode ser que você ainda não tenha uma se criou sua conta fazendo login por meio de um provedor de identidade externo, como o Facebook ou o Google. Você pode adicionar uma senha depois de fazer login na sua página de perfil. Se você ainda não tem uma conta, inscreva-se gratuitamente aqui . Você precisará de um endereço de e-mail verificado para acessar as APIs a seguir, portanto, certifique-se de concluir essa etapa.
Autenticação de solicitações com um token OAuth2 Bearer.
Adicione um cabeçalho de Autorização a cada uma das solicitações de API subsequentes com o valor Bearer YOURACCESSTOKEN (substituindo YOURACCESSTOKEN pelo valor da chave access_token na resposta acima).
Você pode usar este token para solicitar qualquer API à qual seu usuário tenha acesso (o "escopo" padrão obtido acima era muito permissivo – rw:profile rw:issuer rw:backpack , portanto, pode ser usado para fazer qualquer chamada de API que seu usuário precise fazer).
Por exemplo, em uma solicitação para recuperar o perfil do próprio usuário feita com cURL, esse cabeçalho seria definido da seguinte forma: curl ' https://api.badgr.io/v2/users/self' -H "Authorization: Bearer YOURACCESSTOKEN"
Envelope de resposta
Todas as respostas da API V2 Parchment Digital Badges que possuem um corpo envolvem esse corpo em um envelope de resposta JSON, que fornece os dados resultantes da solicitação, bem como metadados sobre o sucesso ou falha da solicitação. O resultado é sempre uma lista ([]), mesmo quando há apenas uma única entidade ou nenhuma entidade no resultado.
Um exemplo de corpo de resposta bem-sucedido:
{ "status": { "description": "ok", "success": true }, "result": [ { "entityId": "g66EErPYSZOyssbD79U3zB" } ]}
Cada uma das entidades nos exemplos a seguir, após a criação bem-sucedida, terá uma propriedade entityId que será usada para identificá-la em chamadas de API subsequentes (normalmente no caminho da solicitação ao criar ou visualizar entidades relacionadas).
Exemplo de corpo de resposta sem sucesso:
{ "status": { "description": "solicitação inválida", "success": false }, "result": [], "validationErrors": ["Erros de formulário (que afetam vários campos) aparecem aqui."], "fieldErrors": { "name": ["Este campo é obrigatório."] }}
As propriedades validationErrors e fieldErrors só aparecem no documento quando status.success é falso.
API do emissor
Algumas das chamadas de API mais importantes que os clientes fazem para a API de Distintivos Digitais da Parchment são para emitir distintivos. Emitir manualmente pela interface web é ótimo, mas para escalar seus programas de emissão de distintivos, você precisa começar a automatizar, e a API de Distintivos Digitais da Parchment facilita isso. Cada distintivo é concedido por um Emissor, então começaremos criando um Perfil de Emissor, depois definiremos a Classe de Distintivo a ser concedida e, finalmente, concederemos uma Declaração dessa Classe de Distintivo.
Cada uma das três requisições iniciais desta seção é uma requisição POST. Recomendamos o uso da API em JSON tanto para o cabeçalho Content-Type do corpo da requisição quanto para o conteúdo do corpo da resposta. Por padrão, se você não especificar um cabeçalho Accept: application/json , o JSON será retornado.
Criar perfil do emissor
Caminho da solicitação : /v2/issuers
Um Perfil de Emissor descreve uma organização ou pessoa que concede Open Badges. Ele é publicado como a classe Perfil de Open Badges https://openbadgespec.org/#Profile .
Propriedades:
- O nome é obrigatório: texto.
- É necessário descrever o conteúdo da string.
- É necessário fornecer um URL . Este deve ser o URL completo de uma página que descreva este emissor/programa.
- A imagem é opcional, deve ser uma string codificada em base64 e pode ser apenas PNG ou SVG. Por exemplo, um pequeno arquivo de imagem PNG deve aparecer assim nos corpos das requisições que exigem um campo de imagem: "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
- O e-mail deve ser um e-mail verificado na conta Parchment Digital Badges do usuário que está se autenticando. Acesse /v2/users/self para recuperar seu perfil e ver seus endereços de e-mail verificados.
Defina BadgeClass
Caminho da solicitação : /v2/issuers/ :issuer_entity_id /badgeclasses. Uma BadgeClass é um tipo de badge que um emissor pode conceder repetidamente (criando várias Asserções dessa BadgeClass, cada uma para um destinatário diferente). Consulte a especificação Open Badges: BadgeClass https://openbadgespec.org/#BadgeClass
Propriedades:
- O nome é obrigatório: texto.
- É necessário descrever o conteúdo da string.
- A imagem é obrigatória e só pode estar no formato PNG ou SVG. Por exemplo, um pequeno arquivo de imagem PNG deve aparecer assim nos corpos das requisições que exigem um campo de imagem: "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mN0nmxRDwADvgGPapFGzwAAAABJRU5ErkJggg=="
- É necessário fornecer critérios. Um ou ambos os seguintes campos, `critérioNarrativo` (uma string formatada em Markdown) e/ou `critérioUrl` (um URL completo de uma página que representa os critérios para este selo), devem ser fornecidos.
- O parâmetro `tags` é opcional. Se presente, deve ser uma lista ([]) de uma ou mais strings;
- O parâmetro `alignments` é opcional. Se presente, deve ser uma lista ([]) de um ou mais objetos JSON, cada um com as seguintes propriedades:
- targetName obrigatório, string
- targetUrl é um URL obrigatório e totalmente qualificado.
- targetDescription (opcional, string)
- targetFramework ( opcional, string) (em qual estrutura de competências este objetivo de alinhamento se enquadra?)
- targetCode opcional, string (existe alguma subtag em targetUrl que diferencie este alvo de outros alvos possíveis que você identificaria com a MESMA URL? Use esta opção somente se o targetUrl for ambíguo.)
Declaração de Problema
Caminho da solicitação : /v2/badgeclasses/ :badgeclass_entity_id /assertions
Uma Asserção é uma instância de uma BadgeClass (tipo de conquista reconhecida por uma entidade emissora) concedida a um destinatário. Uma entidade emissora pode ter várias Asserções de uma determinada BadgeClass concedidas a diferentes destinatários. Consulte a Especificação Open Badges: Asserção https://openbadgespec.org/#Assertion
Propriedades:
- O destinatário é obrigatório (a única propriedade obrigatória) e deve ser um objeto JSON com pelo menos uma chave de identidade . Outras propriedades opcionais do objeto de identidade do destinatário incluem: `type` (qual o tipo de identificador da identidade ? Escolha entre `email` , `telephone` e `url` ); e `hashed` (booleano, indica se a identidade deve ser criptografada na declaração final do Open Badges). Ao receber o objeto da API, a propriedade `plaintextIdentity` , somente leitura, é exibida para mostrar o valor original da identidade , caso esteja oculto pelo hash público (quando `hashed == true` ).
- As evidências podem ser expressas em termos de uma “narrativa” geral e/ou um ou mais “itens de evidência”. `narrative` é uma propriedade opcional que aceita strings formatadas em Markdown. `evidence` é uma propriedade que aceita uma lista ([]) de objetos JSON ({}), cada um contendo uma narrativa e/ou um ID (que é uma URL para uma evidência hospedada em HTTP).
- Observe que a imagem é somente leitura neste endpoint. A imagem "pré-renderizada" será gerada a partir da imagem BadgeClass pelo servidor.
- O parâmetro `issuedOn` é opcional: você pode substituir a data de emissão por uma data no passado. Espera-se um registro de data e hora formatado em ISO 8601, incluindo o identificador do fuso horário. Exemplo: 2018-11-26T13:45:00Z (neste caso, "Z" significa "Zulu", UTC).
- `expires` é uma data de expiração opcional para a Asserção. As expectativas de formato são as mesmas que em `issuedOn` .
- A propriedade `notify` é um parâmetro booleano opcional. Indica se o destinatário deve ser notificado por e-mail (funciona apenas com o tipo de destinatário "e-mail" ). Observação: para divulgações de privacidade obrigatórias, uma notificação por e-mail será enviada ao destinatário após a primeira premiação para cada endereço de e-mail em um servidor específico do Parchment Digital Badges.
Links úteis