Portuguese

Conceito

...

Uma API - (acrônimo de Application Programming Interface, ou  ou Interface de Programação de Aplicação em português, ) é um conjunto de rotinas e padrões estabelecidos por um software para a utilização das suas funcionalidades de seus recursos por aplicativos que não pretendem envolver-se em detalhes da implementação do software, mas apenas usar seus serviços. De modo geral, uma API é composta por uma série de funções acessíveis somente por programação e que permitem utilizar características do software menos evidentes ao utilizador usuário tradicional.

...

...

Desenvolvimento

...

Para o correto desenvolvimento é preciso ter em mente alguns cuidados que devem ser sempre considerados na construção de uma API:

• Nunca

...

•  desenvolva ou solicite qualquer interação com o usuário, seja ela através de telas, mensagens ou perguntas

...

• ;
• Simplifique suas funções, não é uma boa prática construir uma função "faz tudo", separe sempre sua lógica em diversas funções que possam ser executadas de formas distintas

...

• ;
• Evite

...

•  que suas funções dependam do produto, lembre-se que elas poderão ser executadas através de outros produtos ou

...

• serviços

...

• ; e
• Sempre

...

•  desenvolva visando a solução de único objetivo de negócio

...

• . Uma API para manutenção de pedidos não pode conter manutenção de

...

• empresas, por exemplo.

Para iniciar o desenvolvimento de uma API no Logix, crie seu código fonte utilizando o Controle de Fontes Logix e Datasul disponível no GCAD-TOOLS. Nos próximos itens deste documento, serão detalhados os padrões detalhadas as técnicas que devem ser seguidos na construção dos códigos fonte das APIs.

Nomenclatura das Funções

A declaração do nome da função terá fundamental importância neste desenvolvimento, pois é este que definirá se a função da API ficará pública e como será a execução da função a partir de serviços web. Segue abaixo um exemplo de definição:

Image Removed

Sempre delimitada pelo caractere underscore, o nome da função indica como será sua estrutura a partir de cada delimitador, sendo:

1. Nome da API (logr2)
2. Identificador de publicação da função (sem o identificador pub, ela não será publicada)
3. Tipo de execução da função (create)
4. Nome do método (companies)

Abaixo seguem maiores detalhes de como cada uma das informações acima devem ser declaradas.

Nome da API

O primeiro item definido no nome da função deve ser o nome da API seguindo os padrões de desenvolvimento atual onde o início do nome de todas as funções, deve conter o nome do objeto de negócio atual.

Exemplos:

2.1. Métodos de Execução

Os métodos de execução definem qual método de requisição HTTP será utilizado para executar a função. Para aproximar o desenvolvimento das APIs ao desenvolvimento do produto Logix, será possível definir um apelido para os métodos de execução, como create, process e update - uma função definida com o nome logr4_pub_create_companies seria igual a uma função com o nome logr4_pub_post_companies por exemplo. http://www.w3schools.com/tags/ref_httpmethods.asp

Os métodos de execução disponíveis atualmente são:

• POST, CREATE ou PROCESS: para inclusão ou processamento
• PUT ou UPDATE: para modificação
• DELETE: para exclusão
• GET ou QUERY: para recuperar uma ou mais informações

A execução REST da função da imagem acima, após sua publicação, teria uma requisição semelhante a abaixo:

POST /logix-rest/logr4/companies HTTP/1.1
Host: localhost:808

3. Nomenclatura dos Parâmetros

Para gerar os parâmetros de  

TODO: documentar nomenclatura dos parametros

TODO: documentar estrutura JSON

TODO: documentar estrutura XML

TODO: documentar funções de retorno da estrutura

TODO: gerar WADL