Guia de criação da API

Com o Connect Us Cloud, criar APIs é tão fácil quanto estalar os dedos.

Crie APIs RESTful poderosas a partir de fontes de dados atuais com um interface simplificada.

Existem duas maneiras de se projetar API:

  • Criar API (Guia da API): criação de uma nova API utilizando nosso guia rápido de três passos.
  • Versionar (Gerenciador): clonar uma API pré existente e gerar uma nova, com uma nova versão.

Ambas são executados dentro da plataforma, portanto escolha a que melhor se adapta ao seu fluxo de trabalho.

Antes de começar a construir, pense em como sua API com o Connect Us funcionará e planeje quais gatilhos e ações serão construídos.


Pronto? Vamos começar...

O processo de criação de APIs é dividido em três passos:

  • Passo 1: configurações do banco de dados e informações da API;
  • Passo 2: escolher as tabelas (recursos) e métodos;
  • Passo 3: definições para cada coluna e criação de relacionamentos.

A seguir, você pode acompanhar detalhadamente cada uma das etapas.

Passo 1 - Configurações iniciais

Esta etapa consiste em informar qual o banco de dados você utiliza para fazer a gestão dos dados, informar os dados de acesso e em seguida definir as propriedades da sua API.

Primeiro, selecione qual banco de dados dará origem a API, abaixo a lista de bancos homologados:

  • Microsoft SQL Server - a partir da versão 11.0;
  • MySQL - a partir da versão 5.7;
  • Firebird - a partir da versão 2.5;
  • PostgreSQL - a partir da versão 9.6;
  • IBM DB2 - 11.1 ou inferior;
  • Oracle - a partir da versão 12.1;
  • Maria DB - a partir da versão 10.4.
Passo 1

Após selecionado o banco, note que a visualização na direita está separada em duas partes, sendo a primeira para realizar a conexão com o banco de dados e a segunda são as informações e definições da API.


Propriedades do banco de dados:

No exemplo abaixo é utilizado o preenchimento do banco de dados SQL Server, porém muitos campos são comuns e outros especificos de cada tipo de banco.

Insira as informações de acesso ao banco:

  • Conexão: Campo preenchido automaticamente.
  • Host: informe o caminho de onde seu banco está hospedado.
  • Banco de dados: o nome do seu banco.
  • Porta: informe a porta de acesso (Ex.: 3360).
  • Usuário: o nome do usuário com acesso ao banco de dados.
  • Senha: passe a credencial para realizar o login no banco.
  • Testar conexão.

Caso tenha a necessidade, também é possivel informar diretamente a connection string, basta marcar a caixa de seleção exibida abaixo dos campos.

Passo 1
Propriedades da API

Na parte inferior da tela, exibe as informações gerais da API bem como suas configurações de requisições, segurança e visibilidade.

Insira as seguintes informações:

  • Nome da API: o nome desejado para a API (sem espaços e/ou caracteres especiais).
  • Versão: insira a versão da API (Ex.: v1).
  • Segurança: se possuirá token para poder utilizar a API.
    • Manual: o token, ou também chamado clientSecret será criado de maneira manual pelo gerenciador de API do Connect Us Cloud.
    • Automática: automaticamente criado e vinculado a API.
  • Visibilidade: é composto por duas opções de visibilidade.
    • Produção: API criada e publicada em sua totalidade, não sendo mais possível a edição de sua connection string.
    • SandBox: API estará em um ambiente de simulação, com limites de acessos e com a possibilidade de edição da connection string.
  • Requisições por mês: defina a quantidade máxima de chamadas por mês.
  • Requisições por minuto: defina a quantidade máxima de chamadas por minuto.
  • Descrição: insira a descrição sobre a utilização da API, informação somente para acesso interno na plataforma.

Passo 2 - Tabelas e métodos

Chegou o momento de selecionar os recursos de sua API e informar quais métodos (GET, POST, etc) serão habilitados.

Base de dados conectada

A lista exibida são todos os recursos que o Connect Us Clous localizou em seu banco de dados.

Selecione quais recursos farão parte da sua API e utilize o botão de adicionar para vincular e configurar os métodos de cada recurso.

  • Localize e adicione os recursos.
Seleção dos métodos

Após adicionar, é o momento de informar quais permissões cada recurso terá acesso:

  • Utilize os filtros na parte superior para adição rápida dos métodos.
  • Ou utilize os circulos ao lado de cada recurso, que representam os seguintes métodos:
  • Azul: GET.
  • Verde: POST.
  • Amarelo: PUT/PATCH.
  • Vermelho: DELETE.
Bem-vindo ao Connect Us CloudS!

Passo 3 - Relacionamento

Agora que você ja definiu os recursos e seus métodos, configure individualmente cada coluna e adicione as informações mais detalhadas do relacionamento entre os recursos.

Lembre-se de todos os pontos, pois assim você garante que sua API não encontre itens não estipulados ou não definidos.

Configure as colunas

No último passo, você irá definir as informação de:

  • Nome (Alias): defina um nome para as suas tabelas e colunas, alterando sua visibilidade na API mas sem alterar no banco de dados.
  • *PK: informe ou altere qual coluna é a chave primária da sua estrutura.
  • Nulável: defina quais campos não serão obrigatórios nas suas requisições.
  • Computada: marque apenas os valores que são gerados automaticamente, como por exemplo campos auto-incremento.

Itens com (*): Caso seu recurso possua mais de uma PK, informe o Connect Us Cloud dessa informação para melhor desempenho.


Bem-vindo ao Connect Us Cloud!
Relacionamento

Na parte superior da tela, possui um botão de relacionamento. Utilize-o para informar o relacionamento entre as tabelas.

  • Nome: informe um nome para o relacionamento;
  • Tabela pai: Selecione a tabela de origem dos dados;
  • Tabela filha: Selecione qual tabela filha deseja relacionar;
  • Nome (1:N): Nome para a tabela que terá estrutura de um para muitos;
  • Nome (1:1): Nome que terá a estrutura de um pra um;
  • Coluna pai: Campo preenchido automaticamente informando a coluna relacionada da tabela pai;
  • Coluna filha: Selecione a coluna da tabela filha que estará relacionada;
  • Descrição: Descreva as características de utilização do relacionamento.
Tela de relacionamentos

Publicação

Com todas as etapas configuradas corretamente, sua API será publicada e estará disponível para receber chamadas.

Informações importantes:

  • Chamada da API: Link de acesso, clique para realizar a chamada diretamente no navegador ou copie para realizar a chamada em outra plataforma .
  • Documentação: Link de acesso externo, este é o link que seus clientes e parceiros irão receber para ver a documentação de sua API.

Agora que você já definiu recursos e métodos, poderá criar recursos totalmente customizados e ainda adicionar validações de dados e filtros a quem for acessar.

Sandbox

Construir uma API não é uma tarefa de uma única pessoa, ela possui um processo de aprovação e validação sendo uma negociação colaborativa entre equipes. Para isso, atribuimos ao SandBox a capacidade de simular e interagir com sua API RESTful como se já estivesse em produção, mas em um ambiente controlado.

Esse ambiente também pode se estender a clientes e parceiros que precisam de um ambiente de testes para validar suas integrações e trocas de informações, sem impactar em sua base de dados de produção.

Exemplo de API Sandbox.

Diferente das APIs de produção, que possuem configurações fixas de conexão, em APIs SandBox você poderá alterar as configurações de conexão com o banco de dados, garantindo mais possibilidades aos seus testes.

Além disso, é possível ativar versões SandBox para suas APIs de produção sem a necessidade de criar uma nova.

Para configurar e habilitar o SandBox, basta clicar no botão a direita das informações de acesso da API e em seguida clicar em editar acessos.

Exemplo de API Sandbox.

Em seguida, configure seus dados de conexão para a API SandBox.

Exemplo de API Sandbox.

Boas práticas

Na etapa de criação de APIs é importante estar atento a algumas regras e também boas práticas para que seus endpoints funcionem corretamente.

  • Nome e versão iguais: não é possível criar uma nova API com o mesmo nome e versão já utilizados anteriormente.
  • Limites de requisições: a quantidade de requisições por minuto nunca poderá ser maior que a quantidade de requisições por mês.
  • Métodos vazios: ao configurar os métodos para suas colunas, no passo 4, todas as colunas que não possuírem nenhum método definido, serão removidas da configuração. Elas poderão ser adicionadas novamente nas configurações de Estrutura da API.
  • Manter configuração do Banco de Dados: caso suas configurações de API estejam diferentes do que foi previamente configurado em banco, a API não conseguirá realizar chamadas ao servidor.