Formato dos pedidos e respostas

Os endpoints disponibilizados na Web API requerem parâmetros no pedido e devolvem respostas diferentes consoante a operação associada.

Apesar de existirem endpoints com operações específicas para determinadas entidades que dependem da lógica de negócio dessas entidades, os parâmetros de entrada e os resultados estão tipificados para as seguintes operações principais:

• Criação de um registo (POST).
• Atualização de um atributo de um registo (PUT).
• Anulação de um registo (DELETE).
• Consulta de um registo (GET).
• Listagem de todos os registos (GET).
• Listagem de uma página de registos (GET).

Parâmetros

Parâmetros obrigatórios para todos os endpoints

Todos os endpoints têm o seguinte URL base:

https:///api/{account}/{subscription}/{module}/{resource}

Os seguintes parâmetros são sempre necessários em todos os pedidos à Web API e são definidos no URL:

• account: identificador da conta do cliente.
• subscription: identificador da subscrição do cliente.

Para assegurar a autenticação do utilizador e da aplicação é também necessário incluir sempre os seguintes valores nos headers do pedido:

• Authorization: o token obtido no pedido de autenticação.
• Accept: com o valor application.

Mais informação: O que é a Web API?

Parâmetros obrigatórios por tipo de operação

Os outros parâmetros dependem do tipo de operação associado ao endpoint e devem ser definidos no URL, na query string ou no corpo da mensagem, dependendo do parâmetro.

Resultado por tipo de operação

A resposta a cada pedido será sempre um status code que indica o estado da operação e, opcionalmente, um resultado no corpo da mensagem. Esses dois resultados variam também por tipo de operação.

Tipos de operação

Criação de um registo (POST)

URL:

https:///api/{account}/{subscription}/{module}/{resource}

Parâmetros:

• Neste caso o único parâmetro é o próprio registo a criar, serializado em JSON, no corpo da mensagem.

Status code esperado:

• 201 (Created): indica que o registo foi criado com sucesso.

Resultado esperado:

• O identificador do novo registo, serializado em JSON, no corpo da mensagem.

Atualização de um atributo de um registo (PUT)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}/{attributeName}

Parâmetros:

• key: o identificador ou a chave do registo que se pretende atualizar.
• attributeName: o nome do atributo que se pretende atualizar.
• O novo valor do atributo, serializado em JSON, no corpo da mensagem.

Status code esperado:

• 204 (NoContent): indica que o registo foi atualizado com sucesso.

Resultado esperado:

Anulação de um registo (DELETE)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}

Parâmetros:

• key: o identificador ou a chave do registo que se pretende anular.

Status code esperado:

• 204 (NoContent): indica que o registo foi anulado com sucesso.

Resultado esperado:

Consulta de um registo (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}/{key}

Parâmetros:

• key: o identificador ou a chave do registo que se pretende consultar.

Status code esperado:

• 200 (OK): indica que o registo foi retornado com sucesso.

Resultado esperado:

• O registo selecionado, serializado em JSON, no corpo da mensagem.

Listagem de todos os registos (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}

Parâmetros:

Status code esperado:

• 200 (OK): indica que os registos foram retornados com sucesso.

Resultado esperado:

• A lista de registos, serializada em JSON, no corpo da mensagem.

Listagem de uma página de registos (GET)

URL:

https:///api/{account}/{subscription}/{module}/{resource}?page={page}&pageSize={pageSize}

Parâmetros:

• page: o número da página que se pretende obter.
• pageSize: o número de registos que se pretende obter no resultado.

Status code esperado:

• 200 (OK): indica que os registos foram retornados com sucesso.

Resultado esperado:

• A lista de registos, serializada em JSON, no corpo da mensagem.

Resultados especiais

Os resultados documentados antes correspondem às situações de sucesso, quando o endpoint executa sem erros e realiza a operação esperada. A Web API devolve outros códigos em caso de erro e, nesses casos, pode devolver outros resultados com informação sobre os erros (por exemplo, quando a validação dos parâmetros falha).

Pode consultar mais informação sobre esses cenários no seguinte documento:

• Mensagens de erro