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	Requisição não definida como na Especificação TALQ. Parâmetros inválidos
404 Not Found	Recursos ou recursos relacionados não foram encontrados.
409 Conflict	Conflito com o recurso especificado.
422 Unprocessable Content	Entidade não processável: A solicitação estava bem formada, mas não pôde ser seguida devido a erros semânticos.
500 Internal Server Error	Erro interno do servidor que não depende do usuário.

*404 resource(recurso), vai geralmente se referir ao(s) recurso(s) relacionado(s) a request, então, groups, devices, functions ou calendars.
Exemplo: uma requisição "Update a Talq Device Class" para status code 404 retornaria "Device class or related resource not found".

Possíveis Erros das Requisições

Erro TALQ	Descrição	HTTP Status Code
headerMissing	O cabeçalho da requisição está ausente.	400 Bad Request
headerValueNotValid	O valor do cabeçalho fornecido é inválido.	400 Bad Request
parameterMissing	Parâmetro obrigatório não foi fornecido na requisição.	400 Bad Request
parameterValueNotValid	O valor de um parâmetro fornecido é inválido.	400 Bad Request
payloadError	Erro na carga da requisição; o conteúdo está incorreto ou incompleto.	400 Bad Request
resourceNotFound	O recurso solicitado não foi encontrado.	404 Not Found
resourceConflict	Conflito com o estado atual do recurso, geralmente devido a uma duplicação.	409 Conflict
relatedResourceNotFound	Um recurso relacionado ao recurso atual não foi encontrado.	404 Not Found
deletingResourceIsReferred	Tentativa de deletar um recurso que está sendo referenciado por outros recursos.	409 Conflict
serviceConstraintExceeded	Violação de uma restrição do serviço, como limite de recursos ou políticas de uso.	403 Forbidden
assignmentEntityNotValid	A entidade atribuída não é válida.	400 Bad Request
assignmentAddressNotValid	O endereço atribuído não é válido.	400 Bad Request
overrideCommandNotValid	O comando de substituição fornecido não é válido ou está incorreto.	400 Bad Request
overrideAddressNotValid	O endereço de substituição fornecido não é válido ou está incorreto.	400 Bad Request

Exemplo:

[
    {
        "key": "parameterMissing",
        "description": "Custom client/vendor header is missing",
        "references": []
    }
]

[
    {
        "key": "resourceNotFound",
        "description": "Gateway with clientAddress 'd3cfd8f1-a689-446b-9ee2-e8ad1af334fb' not found",
        "references": []
    }
]

*references retorna o endereço do recurso relacionado que causou o erro, podendo ser groups, devices, functions e calendars

Autenticação e Proteção de Rotas

Protocolo TLS

Transport Layer Security (TLS), é um protocolo de segurança comumente utilizado em aplicações cliente-servidor, de forma que a comunicação entre as partes seja criptografada.

Seu funcionamento, se da por uma "criptografia de chave pública", dado um par de chaves, sendo uma pública e outra privada, o princípio de seu funcionamento é que qualquer coisa criptografada com a chave pública só pode ser descriptografada com a chave privada. Se um servidor descriptografa uma mensagem, criptografada com uma chave pública, isso é garantia que o mesmo possui a chave privada equivalente.

No contexto do protocolo TLS, temos os certificados TLS, que de forma resumida, é um arquivo de dados que possui informações para verificar a identidade do cliente/dispositivo ou servidor. O certificado TLS que possui a chave pública, por exemplo.

Um processo típico de estabelecimento de conexão entre as partes, utilizando do TLS, seria:

Cliente conecta com o servidor;

Servidor apresenta seu certificado TLS;

Cliente verifica o certificado;

Certificado verificado, cliente e servidor trocam informações em um meio criptografado.

Mutual TLS

O Mutual TLS (mTLS), é baseado no protocolo TLS, e implementado no projeto do IoT Hub. O mesmo difere em alguns aspectos do "TLS padrão", e garante uma camada a mais de segurança. No contexto do IoT Hub, faz bastante sentido seu uso, visto que, também verifica conexões com dispositivos clientes que não seguem um processo de login, tais como dispositivos da Internet das Coisas (IoT).

No processo de conexão entre as partes, temos algumas etapas extras, no caso, não só o servidor apresenta seu certificado TLS, mas o cliente também deve apresentar o seu, o qual deve ser verificado pelo servidor.

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
POST	/talq/device-classes	Dado uma lista de classes de dispositivo. Anuncia as classes de dispositivo suportadas pelo gateway e ainda não anunciadas
PUT	/talq/device-classes	Atualiza classes de dispositivo existentes suportadas pelo gateway
DELETE	/talq/device-classes/{nomeClasse}	Exclui uma classe de dispositivo existente
PUT	/talq/device-classes/{nomeClasse}	Atualiza UMA classe de dispositivo existente suportada pelo gateway
POST	/talq/devices	Inclui uma lista de dispositivos
GET	/talq/devices	Lista os dispositivos existentes
PATCH	/talq/devices	Atualiza parcialmente uma lista de dispositivos. Essa operação pode apenas atualizar e adicionar novas funções/valores de atributos ao dispositivo
PUT	/talq/devices	Atualiza uma lista de dispositivos existentes. Substitui toda a definição de dispositivo existente. As funções de dispositivo existentes serão substituídas pelas especificadas nessa chamada
DELETE	/talq/devices/{enderecoDispositivo}	Exclui um dispositivo existente
GET	/talq/devices/{enderecoDispositivo}	Lista um dispositivo específico
PATCH	/talq/devices/{enderecoDispositivo}	Atualiza parcialmente um dispositivo. Essa operação pode apenas atualizar e adicionar novas funções/valores de atributos ao dispositivo
PUT	/talq/devices/{enderecoDispositivo}	Atualiza um único dispositivo. Substitui toda a definição de dispositivo existente. As funções existentes do dispositivo serão substituídas pelas especificadas nessa chamada.
GET	/talq/devices/{deviceAddress}/{idFuncao}	Obter uma única função de um dispositivo por seu endereço e ID de função
GET	/talq/devices/{deviceAddress}/{idFuncao}/{nomeAtributo}	Obter um único atributo de uma função de um dispositivo por meio de seu endereço, ID da função e nome do atributo
GET	/talq/groups	Lista os grupos TALQ. De acordo com as especificações um grupo pode ser composto por "Dispositivos", "Funções" e outros grupos
GET	/talq/groups/{groupAddress}	Lista um grupo específico
POST	/talq/services	Inclui uma lista de serviços TALQ. Cada serviço do protocolo TALQ define de maneira detalhada como as mensagens devem ser trocadas e como a aplicação deve se comportar para modificar atributos de funções. Isso significa que para cada serviço, há uma sequência ou um padrão de comunicação predefinido.

Referências

Cloudflare. "O que é certificado SSL?" Disponível em: https://www.cloudflare.com/pt-br/learning/access-management/what-is-mutual-tls/. Acesso em: 21 nov. 2024.

Cloudflare. "O que é um handshake TLS?" Disponível em: https://www.cloudflare.com/pt-br/learning/ssl/what-happens-in-a-tls-handshake/. Acesso em: 13 mar. 2025.

API TALQ

Retornos das Requisições#

Possíveis Erros das Requisições#

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

Protocolo TLS#

Mutual TLS#

Endpoints#