Retornos das Requisições

HTTP Status Code	Descrição
200 OK	A solicitação foi bem-sucedida. O resultado e o significado de “sucesso” dependem do método HTTP.
201 Created	A solicitação foi bem-sucedida, e um novo recurso foi criado como resultado.
400 Bad Request	Erro no processamento da requisição devido a passagem de parâmetros inválidos.
403 Forbidden	Operação não permitida para a entidade especificada.
404 Not Found	Recursos ou recursos relacionados não foram encontrados.
409 Conflict	Conflito com o recurso especificado.
500 Internal Server Error	Erro interno do servidor que não depende do usuário.

Possíveis Erros das Requisições

Código do Erro	Descrição	HTTP Status Code
INVALID_PARAMETERS	Os parâmetros passados não são válidos	403 Forbidden
ENTITY_NOT_FOUND	Entidade especificada não foi encontrada	404 Not Found
ENTITY_ALREADY_EXISTS	A entidade especificada já existe	409 Conflict
CLIENT_IDENTIFICATION_MISSING	A identificação do cliente está ausente	403 Forbidden
OPERATION_NOT_ALLOWED_FOR_VENDOR	Operação não permitida para o fornecedor especificado	403 Forbidden
INVALID_HEADER	Cabeçalho especificado é inválido	400 Bad Request
RESOURCE_CONFLICT	Conflito com o recurso especificado	409 Conflict
INTERNAL_SERVER_ERROR	Erro interno no servidor	500 Internal Server Error

Exemplo:

{
    "status": "error",
    "error": {
        "error_code": "INVALID_PARAMETERS",
        "message": "Invalid client instance UUID"
    }
}

{
    "status": "error",
    "error": {
        "error_code": "OPERATION_NOT_ALLOWED_FOR_VENDOR",
        "message": "Operation not allowed for the specified vendor"
    }
}

Autenticação e Proteção de Rotas

JSON Web Token

O JSON Web Token (JWT) é um padrão de autenticação e troca segura de informações entre duas partes, normalmente um cliente e um servidor. JWTs são usados para verificar a identidade do usuário e garantir que ele tenha permissão para acessar certos recursos.

Um token JWT, quando criado, é assinado pelo servidor com uma chave secreta ou certificado, tornando-o seguro contra alterações. Depois, o token é enviado ao cliente e anexado em futuras requisições. Como o servidor confere o token ao receber a requisição, ele pode garantir que o cliente tem permissão.

Para mais informações, consulte o artigo da Cloudflare.

Endpoints

Segue uma breve decrição dos endpoints assim como o tipo de requisição e a rota do mesmo. Para detalhes do corpo da requisição e resposta, consultar na seção API o endpoint em questão.

Verbo HTTP	Endpoint	Descrição
GET	/guia/devices	Lista os dispositivos IoT
GET	/guia/devices/:uuid	Lista um dispositivo IoT em específico
PATCH	/guia/devices	Atualização parcial de uma lista de dispositivos existentes. Atualiza parcialmente a definição do dispositivo existente. Para o vetor de funções, cada elemento passado será comparado com os itens do vetor de funções existente usando o ID. Se eles corresponderem, a função existente será atualizada. Se não houver correspondência, a função será adicionada.
PATCH	/guia/devices/:deviceUuid	Atualiza parcialmente a definição do dispositivo existente. Para o vetor de funções, cada elemento passado será comparado com os itens do vetor de funções existente usando o id. Se eles corresponderem, a função existente será atualizada. Se não houver correspondência, a função será adicionada. Para cada função, somente os atributos passados serão atualizados na função existente.
PATCH	/guia/devices/:deviceUuid/:functionUuid	Atualização parcial de uma lista de atributos de uma função, somente os atributos passados serão atualizados.
PATCH	/guia/devices/:deviceUuid/:functionUuid/:attributeUuid	Atualiza parcialmente um atributo.
GET	/guia/devices/:deviceUuid/attribute-history	Retorna o histórico de valores de atributos do dispositivo especificado
PATCH	/guia/devices/:deviceUuid/setExternalId	Atualiza o `external_id` do dispositivo IoT
POST	/guia/devices/fromIdentifiedMaterial	Cria um dispositivo usando um material identificado do Guia. A validação da existência do dispositivo pode variar de acordo com o fornecedor.
POST	/guia/devices/multipleFromIdentifiedMaterial	Cria dispositivos usando materiais identificados do Guia. A validação da existência do dispositivo pode variar de acordo com o fornecedor.
POST	/guia/devices/multipleDevicesPartialUpdate	Atualização parcial de uma lista de dispositivos existentes. A única diferença entre essa operação e PATCH /devices é que essa operação recebe um formato diferente (por causa da fila de mensagens).
POST	/guia/devices/partialDeviceUpdate	Atualiza parcialmente a definição do dispositivo existente. A única diferença entre essa operação e PATCH /devices/:deviceUuid é que essa operação recebe um formato diferente (por causa da fila de mensagens).
POST	/guia/devices/attributeValueUpdate	Atualização parcial de um atributo. A única diferença entre essa operação e PATCH /devices/:deviceUuid/:functionUuid/:attributeUuid é que essa operação recebe um formato diferente (por causa da fila de mensagens).
POST	/guia/devices/functionUpdate	Atualização parcial de uma lista de atributos de uma função, somente os atributos passados serão atualizados. A única diferença entre essa operação e PATCH /devices/:deviceUuid/:functionUuid é que essa operação recebe um formato diferente (por causa da fila de mensagens).
GET	/guia/vendors	Consulta a todos os fornecedores vinculados ao cliente Guia atual.
POST	/guia/vendor	Cria um fornecedor
PATCH	/guia/vendor/:vendorUuid	Atualiza dados de um fornecedor existente, como nome, status, parques de serviço associados, etc
PATCH	/guia/photoVendor/:vendorUuid	Adiciona/atualiza a foto de um fornecedor
GET	/guia/device-classes	Consulta a todas as classes de dispositivos vinculadas ao cliente atual do Guia.
GET	/guia/device-classes/:deviceClassUuid	Consulta uma classe de dispositivo específica vinculada ao cliente atual do Guia.
GET	/guia/device-classes/:deviceClassUuid/functions	Consulta a todas as funções da classe de dispositivo especificada vinculada ao cliente Guia atual.
GET	/guia/functions	Consulta a todas as funções vinculadas ao cliente atual do Guia.
GET	/guia/functions/:functionUuid/attributes	Consulta os atributos de um função
GET	/guia/functionTypes	Consulta os tipos de função para o cliente atual do Guia
GET	/guia/functionAttributes	Consulta os atributos do cliente atual
GET	/guia/attributes	Consulta os atributos dos dispositivos do cliente atual do Guia
GET	/guia/gateways	Operação especial para consultar os gateways, que são dispositivos, mas têm a função de ser um “pai” para classes de dispositivos, dispositivos, funções e atributos.
GET	guia/groups	Consulta a lista de grupos
POST	guia/groups	Cria grupo(s)
PUT	guia/groups	Atualiza grupo(s)
GET	guia/groups/count	Retorna o número de grupos existentes
DELETE	guia/groups/:groupAdress	Deleta um grupo através de seu endereço
GET	guia/groups/:groupAdress	Consulta um grupo através de seu endereço
PUT	guia/groups/:groupAdress	Atualiza um grupo através de seu endereço
PUT	guia/groups/:groupAdress/members	Adiciona um ou mais membros a um grupo
GET	guia/groups/:groupAdress/members/count	Retorna o número de membros de um grupo
DELETE	guia/groups/:groupAddress/members/:resource/:address/:functionUuid?	Deleta um membro de um grupo

Referências

Cloudflare. "O que é autenticação baseada em tokens?" Disponível em: https://www.cloudflare.com/pt-br/learning/access-management/token-based-authentication/. Acesso em: 21 nov. 2024.

API GUIA

Retornos das Requisições#

Possíveis Erros das Requisições#

Autenticação e Proteção de Rotas#

JSON Web Token#