Consumindo uma API

Todas as funcionalidades dos sistemas que compõe a plataforma estão disponíveis no formato de Serviços REST.

Sendo assim qualquer uma dessas chamadas pode ser realizada à partir de um client que consiga realizar chamadas HTTP.

Neste tutorial veremos como realizar a chamada de autenticação e obtenção os dados do usuário logado.

SOBRE O TUTORIAL

Para execução deste tutorial, as seguintes ferramentas devem estar instaladas em seu computador

• Postman – Ferramenta para desenvolvimento de APIs

REALIZANDO AS CHAMADAS

No Postman clique em environments, conforme a imagem abaixo:

Clique em create environment, informe um nome para seu environment e adicione a chave

com a URL "https://api.senior.com.br"

INVOCANDO A AUTENTICAÇÃO

Existem duas formas de autenticar-se na plataforma para consumir as APIs.
A primeira é utilizando um usuário e senha de uma usuário ativo na empresa na plataforma Senior X. Esse usuário e senha são os mesmos utilizados para acessar a plataforma SeniorX através da tela de login.
Outra opção é utilizando o recurso de Aplicações, onde é gerada uma senha exclusiva para o consumo de API.

Com usuário e senha

Em uma aba de chamadas, selecione um request do tipo POST

No campo de URL adicione

No HEADER adicione o client_id da aplicação:

Para mais detalhes sobre como obter o client_id CLIQUE AQUI

No body do request adicione um JSON com os atributos

e

conforme a imagem abaixo:

Na aba Test adicione o seguinte código

Isso adicionará uma variável de ambiente com o token, assim não será necessário alterar o valor do header authentication em cada chamada testada posteriormente a cada nova autenticação.

Clique em send e será apresentado na área inferior o response com o token e demais dados da autenticação.

INVOCANDO O ENDPOINT

Invocaremos o endpoit que retorna os dados do usuário logado.
Para invocá-lo, selecione em uma nova aba um request do tipo GET

A URL

Os dados de autenticação, na aba Headers, a chave

e o valor

que buscará o valor setado na variável global no momento da autenticação.

Lembre-se de adicionar também o client_id da aplicação no HEADER da requisição.

Clique em send e será apresentado na área inferior o response, com o os dados do usuário logado.

UTILIZANDO A APLICAÇÃO

O cadastro de uma aplicação é equivalente a de um usuário, tendo como diferença que uma aplicação não possui usuário e senha, mas sim chave e segredo. Sendo assim essas informações não seguem a política de senha portanto não expiram.

Para cadastrar uma aplicação, acesse o menu "Tecnologia > Administração > Gerenciamento de Aplicações".

Clicando em "Nova aplicação", basta informar Nome e Descrição.
Após salvar a aplicação, serão geradas as chaves.

Uma aplicação quando cadastrada não possui permissões associada, elas podem ser configuradas através da tela de gerenciamento de papéis, onde é possível adicionar e remover uma aplicação em um ou mais papéis.

Ao processar requisições de uma aplicação, a plataforma envia o nome da aplicação na mensagem como um usuário comum, assim a verificação de permissões é a mesma não importanto se é um usuário ou uma aplicação que está fazendo a chamada para a plataforma.

O login de uma aplicação deve ser feita através da primitiva https://api.senior.com.br/platform/authentication/anonymous/loginWithKey que recebe como parâmetro: chave, segredo, nome do tenant obrigatoriamente e escopo opcionalmente.

TIPOS DE PARÂMETROS

Cada serviço possui seus parâmetros e cada parâmetro possui um tipo, existem alguns tipos pré-definidos, que são os tipos primitivos, e outros tipos são definidos pelo serviço, normalmente para agrupar um conjunto de tipos primitivos sobre algum separação lógica. Em um exemplo fictício, um colaborador tem seu nome, idade, e um dependente, o nome e idade seriam tipos primitivos, string e integer, respectivamente. Já o dependente seria um tipo definido pelo serviço, que também possui um nome e idade.

Mais detalhes sobre os tipos de dados disponíveis acesse https://dev.senior.com.br/documentacao/guia-de-api/formato-de-dados/