API: Como gerenciar times

A API do Learning.Rocks permite o gerenciamento de Times, que são parte fundamental da estratégia educacional da empresa, pois possibilitam que missões, espaços, games e notificações sejam direcionados apenas a grupos específicos de usuários.

Clicando aqui você pode acessar a collection completa de Teams.

A collection Teams permite realizar as seguintes ações:

• Listar os times existentes;
• Criar um novo time;
• Deletar um time já existente;
• Atualizar um time já existente;
• Adicionar usuários a um time;
• Remover usuários de um time.

Existem dois caminhos para gerenciar os times de usuário. O primeiro é a partir dos endpoints que serão explicados neste artigo, e o segundo é pelos endpoints de usuários. A principal diferença entre os dois é a lógica de funcionamento, pois via “teams”, é possível adicionar/remover o usuário de um time específico, sem necessariamente informar os outros times que ele faz parte. Já via “users”, se for necessário adicionar o usuário à um time, todos os times devem ser sinalizados, tanto os antigos quanto novos.

Como listar os times existentes

O endpoint “Get All Teams” permite listar todos os times existentes no ambiente. O retorno da requisição inclui, entre outros dados, o ID de cada time, informação essencial para gerenciar a participação de usuários via API.

Para obter a lista, basta enviar o comando GET para a URL: https://user.skore.ai/v1/teams.

Se necessário, é possível incluir parâmetros adicionais na pesquisa:

• search: Busca um time pelo nome;
• user_ids: Retorna os times dos quais os usuários informados fazem parte;
• space_ids: Retorna os times associados aos espaços informados;
• skip: Define o número de registros que devem ser ignorados (paginação);
• take: Define o número máximo de registros que devem ser retornados.

Exemplo de uma request e response utilizando o filtro user_ids:

Criar um time

Para criar um time, basta enviar o comando POST para a URL: https://user.skore.ai/v1/teams

No body da requisição, os dados abaixo devem ser enviados:

• name: Nome do time que está sendo criado;
• user_ids: Lista de IDs dos usuários que irão compor o novo time. Caso o campo seja enviado em branco, o time será criado sem usuários (essa informação pode ser atualizada posteriormente);
• space_ids: Lista de IDs dos espaços que serão filtrados pelo novo time. Caso o campo seja enviado em branco, o time será criado sem filtro de espaços (essa informação também pode ser atualizada posteriormente).

Após a criação, a API retornará os dados do time criado, incluindo o ID atribuído a ele.

Exemplo de request e response:

Deletar um time

Para deletar um time, basta enviar o comando DELETE para a URL: https://user.skore.ai/v1/teams/id, sendo que o campo “id” deve ser trocar pelo id do time que será excluído.

Após a execução da ação, não é possível reverter a exclusão de um time.

Exemplo de request e response:

Atualizar um time

Para atualizar um time, basta enviar o comando PATCH para a URL: https://user.skore.ai/v1/teams/id, sendo que o campo “id” deve ser trocado pelo id do time que será atualizado.

As informações que podem ser atualizadas são:

• name: Nome do time.
• space_ids: ID dos espaços que serão filtrados pelo time.

Exemplo de request e response:

Adicionar usuário a um time

Para adicionar usuários a um time, é necessário enviar um POST para a URL: https://user.skore.ai/v1/teams/id/users, sendo que o campo “id” deve ser trocado pelo id do time que receberá novos usuários.

No body, é necessário enviar a linha user_ids [] , com os ids dos usuários que serão incluídos no time dentro dos colchetes.

Essa ação não altera a participação do usuário em outros times; ele será simplesmente inserido no novo time especificado.

Exemplo de request e response:

Remover usuário de um time

Para remover todos os usuários de um time, é necessário enviar um DELETE para a URL: https://user.skore.ai/v1/teams/id/users?, sendo que o campo “id” deve ser trocado pelo id do time que terá usuários removidos.

Para remover apenas um usuário de um time, é necessário seguir a estruturauser_ids=:userId, substituindo userId pelo ID do usuário a ser removido.. Exemplo da URL para remover apenas um usuário: https://user.skore.ai/v1/teams/id/users?user_ids=userId.

Para remover mais de um usuário de um time, é necessário seguir a estrutura a estrutura user_ids[]=:userId1&user_ids[]=:userId2&user_ids[]=:userId3, substituindo cada campo userId1, userId2 e userId3, pelos IDs dos usuários correspondentes que serão removidos . Exemplo da URL para remover mais de um usuário: https://user.skore.ai/v1/teams/id/users?user_ids[]=userId1&user_ids[]=userId2.

Essa ação não irá influenciar nos outros times que o usuário faz parte, ele apenas será removido do time listado.

Exemplo de request e response: