====== 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. ===== O que é ?===== 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" ===== Documentos de Referência ===== Os documentos utilizados como referencia foram o site de [[http://eping.governoeletronico.gov.br/|Padrões de Interoperabilidade de Governo Eletrônico - ePING]] e o Arquivo {{ :pres:gerti:arquitetura:arquiteturas:diretrizes_para_implementacao_de_camada_de_servicos_para_comunicacao_entre_orgaos_do_estado_de_goias.pdf | Diretrizes }} mantido pelo [[https://github.com/goias|Estado de Goiás]]. ==== e-PING Federal ==== 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/]]. === Classificação das especificações técnicas === 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. === Sobre Segurança === 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 [[http://www.iti.gov.br/icp-brasil|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. ^ Componente ^ Especificação ^ Situação ^ Tabela ^ | Algoritmo para transporte | RSA | **A** | Tabela 6 – Criptografia | | Assinaturas XML |Sintaxe e Processamento de assinatura XML (XMLsig) conforme definido pelo [[http://www.w3.org/TR/xmldsig-core/|W3C]] | **A** | Tabela 7 – Desenvolvimento de Sistemas| === Organização e Intercâmbio de Informações === A Comunicação pode ser feita por [[http://www.w3.org/XML|XML]] ou por [[http://www.ietf.org/rfc/rfc4627.txt|JSON]], desde que se mantenha os padrões adotados. === Áreas de Integração para Governo Eletrônico === A forma de comunicação deve ser realizada por Web Service. ^ Componente ^ Especificação ^ Situação ^ Tabela | Protocolo para acesso a Web Service | SOAP v1.2, como definido pelo [W3C](http://www.w3.org/TR/soap12-part0/ ) **Rest**: HTTP/1.1 (RFC 2616) | **A** | Tabela 18 – Web Services| | Descoberta de Web Services Governamentais | [DWSG](http://www.governoeletronico.gov.br/) EPING | **E** | Tabela 18 – Web Services| ==== e-PING Goiás ==== Detalhes importantes encontrados dentro do PIN da Secretária do Estado de Goiás, que devem ser mencionados. Aqui você pode encontrar o {{ :pres:gerti:arquitetura:arquiteturas:diretrizes_para_implementacao_de_camada_de_servicos_para_comunicacao_entre_orgaos_do_estado_de_goias.pdf | documento }}na integra. === Sobre Segurança === A sugestão é o uso de [[http://oauth.net/2/|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 [[http://www.deanhume.com/Home/BlogPost/a-simple-guide-to-using-oauth-with-c-/49|Exemplo de uso do OAuth 2]]. === Organização e Intercâmbio de Informações === A Comunicação pode ser feita por [[http://www.ietf.org/rfc/rfc4627.txt|JSON]], seguindo os padrões adotados. === Áreas de Integração para Governo Eletrônico === A forma de comunicação deve ser realizada por Web Service via RESTful, usando HTTP. === Documentação === Documentação deve seguir o padrão de Open API, utilizando o [[http://swagger.io/specification/|Swagger]]. === Tradução de Nomenclatura === ^ Esperado ^ O que é ^ Exemplo ^ | PageSize | limit | Utilizado na query string, ex.: Consultar 1000 pessoas qeue tenham idate igual a 18. pessoa?idade=18&limit=1000| | Page | offset | Utilizado na query string, buscar apartir do registro número 2000. Exemplo: Consultar 1.000 pessoas que tenham a idade igual a 18, iniciando pelo 2.000: pessoa?idade=18&offset=2000&limit=1000| | TotalCount | Content-Range | Deve estar no header, ele contêm a quantidade de registros da pagina atual, exibindo 1.000 registros de 10.000: *0-999/1000*| === Respostas Esperadas === 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. ^ Código ^ Descrição ^ | 200 | Requisição completa | | 204 | Sem retorno de dados | | 206 | Existem mais dados a serem retornados | | 400 | Requisição inválida | | 401 | Não autorizado | | 403 | Sem permissão | | 408 | Timeout da requisição | | 416 | Intervalo solicitado inválido | | 422 | Não foi possível processar o conteúdo da mensagem. | | 500 | Erro interno no servidor | | 503 | Serviço indisponível | | 504 | Timeout do Gateway | | 522 | Timeout do Servidor | ===== Na Prática ===== Escrever/Definir.