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, a 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.

#TODO
    DEFINE lr_return RECORD
                         length INTEGER, #total registros
						 #RECORD com o conteúdo da empresa criada.
                         data RECORD LIKE empresa.*,
                         #RECORD com a mensagem de retorna da função.
                         msg  RECORD
                                  type   SMALLINT,
                                  code   SMALLINT,
                                  detail CHAR(500)
                              END RECORD
                     END RECORD

2. Nomenclatura das Funções

Para gerar a estrutura e pontos de entrada das APIs, a ferramenta deverá verificar os padrões de nomenclatura de funções - conforme descritos no documento TODO. O nome da função indicará como ficará o nome e o método de chamada através do WebService.

Exemplo:

#------------------------------------------------------------------------------#
FUNCTION logr4_pub_create_companies()
#------------------------------------------------------------------------------#
END FUNCTION

Image Removed

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

1. Código da API (logr4)
2. Identificador de publicação da função (sem o identificador pub, ela não será publicada)
3. Método de execução da função (create - verificar o item Métodos de Execução)
4. Nome da função (companies)

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.

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

...

Nos próximos itens deste documento, serão detalhadas as técnicas que devem ser seguidas na construção do código fonte da API.