Referência da API DUO¶

O DUO é uma plataforma de email e SMS marketing. Este documento cobre a API REST.

Funcionamento Geral¶

O DUO foi concebido de forma a que a aplicação web funcione como cliente da API REST. Os URLs da aplicação web são entrypoints da API que respondem com interfaces humano-máquina quando confrontados com uma preferência text/html, ou JSON analisável por máquina quando o cabeçalho Accept solicita application/json.

Autenticação¶

A autenticação requer um par (username, password). Cada conta de utilizador tem um username e qualquer número de passwords. Uma password é a password da conta; as restantes pertencem a objetos API Key, que podem ser gerados na aplicação.

• Utilize a password da conta para interação humana com o DUO.
• Utilize API Keys para integração máquina-a-máquina — podem ser revogadas a qualquer momento.

Dois mecanismos de autenticação¶

HTTP Auth Básica — Envie o par (username, password) conforme definido no RFC 7617 em cada pedido.

Autenticação baseada em sessão — O mecanismo utilizado pela aplicação web. Submeta um POST para /login/, receba um token de sessão e envie-o como cookie com o nome sergiosgc_auth em cada pedido. Termine com um POST para /logout/.

Encapsulamento de Verbos HTTP¶

Nem todas as rotas aceitam os verbos HTTP PUT/DELETE nativos. Quando um verbo nativo devolve Requested URL not found … for HTTP verb PUT, enviar um POST para o mesmo URL com um campo adicional x-verb (form-encoded) com o verbo pretendido — p. ex. x-verb=PUT. É o mecanismo que a própria aplicação web usa.

Envelope de Resposta¶

Cada resposta JSON é um dicionário com duas chaves:

HTTP 200 é devolvido quando o código da aplicação é executado corretamente. Se a operação falhar por motivos ao nível da aplicação, a resposta JSON apresentará success: false.

Quando success é false, data conterá um dicionário com pelo menos uma chave "error" contendo uma descrição textual do erro.