Web API

Este tópico visa descrever todo o processo de utilização de uma web api, incluindo a parte prática e a teórica.

API é um conjunto de rotinas e padrões de programação para acesso a um aplicativo de software ou plataforma baseado na Web. A sigla API refere-se ao termo em inglês “Application Programming Interface” que significa em tradução para o português “Interface de Programação de Aplicativos”

Os documentos utilizados como referencia foram o site de Padrões de Interoperabilidade de Governo Eletrônico - ePING e o Arquivo Diretrizes mantido pelo Estado de Goiás.

Detalhes importantes encontrados dentro do e-Ping do governo federal, que devem ser mencionados. O e-PING pode ser encontrado na integra através do site: http://eping.governoeletronico.gov.br/.

A legenda adotada dentro do e-ping federal.

Adotado (A): item adotado pelo governo como padrão na arquitetura ePING, tendo sido submetido a um processo formal de homologação. Os componentes com padrão nível Adotado devem ser obrigatoriamente adotados em novos produtos/projetos de TI;

Recomendado (R): item que atende às políticas técnicas da ePING, é reconhecido como um item que deve ser utilizado no âmbito das instituições de governo, mas ainda não foi submetido a um processo formal de homologação. Os componentes de nível Recomendados *não são obrigatórios*, porém sugeridos para adoção em novos produtos/projetos de TI;

Em Transição (T): item que o governo não recomenda, por não atender a um ou mais requisitos estabelecidos nas políticas gerais e técnicas da arquitetura;

Em Estudo (E): componente que está em avaliação e poderá ser adotado, assim que o processo de avaliação estiver concluído.

O item 2.1.7 relata que devemos gerar logs para permitir auditorias e provas materiais, assim como utilizar autenticidade dos registros armazenados. Fica então a cargo do Analista/Owner do projeto se devemos ou não gerar log das operações realizadas. Esta opção precisa estar especificada no requisito quando e quais campos devem ser tratados.

O item 2.1.9 relata que devemos utilizar as regras da ICP-Brasil para controle de acesso, assinatura digital e assinatura de código. Para adotar totalmente as definições de regras do ICP, o sistema como um todo do tribunal de contas do estado de goiás precisará ser reavalido e adaptado para atender nova requisição. Fica também este item a cargo do Analista/Owner do projeto se devemos ou não utilizar estas regras.

A Comunicação pode ser feita por XML ou por JSON, desde que se mantenha os padrões adotados.

A forma de comunicação deve ser realizada por Web Service.

Detalhes importantes encontrados dentro do PIN da Secretária do Estado de Goiás, que devem ser mencionados. Aqui você pode encontrar o documento na integra.

A sugestão é o uso de OAuth2, utilizando o *grant_type=client_credentials*, para permitir o acesso ao token de autenticação.

Exemplo do documento:

 POST https://api.oauth2server.com/token
 grant_type=client_credentials&
 client_id=CLIENT_ID&
 client_secret=CLIENT_SECRET 

Exemplo de uso do OAuth 2.

A Comunicação pode ser feita por JSON, seguindo os padrões adotados.

A forma de comunicação deve ser realizada por Web Service via RESTful, usando HTTP.

Documentação deve seguir o padrão de Open API, utilizando o Swagger.

Estas são as premissas genéricas de comunicação:

• 1xx (Informal): A requisição foi recebida, continuando o processo;
• 2xx (Sucesso) : A requisição foi recebida com sucesso, entendida e aceita;
• 3xx (Redirecionamento): É necessária alguma ação adicional para que a ação seja concluída;
• 4xx (Erro Cliente): A requisição contém sintaxe inválida ou não pode ser realizada;
• 5xx (Erro Servidor): O servidor falhou ao tratar uma requisição aparentemente válida.

Aqui você tem uma relação mais detalhada dos código de retorno esperados pelo cliente.

Escrever/Definir.