March 3, 2016
Petterson
Andrade

Como expor APIs na prática - Parte 1

Confira nosso vídeo abaixo sobre Design de APIs:

Mais do que algumas linhas de código!

Expor APIs tornou-se uma necessidade que supera a troca de informações entre máquinas.Estamos na Economia de APIs. Negócios são criados com base em software. E não apenas um software, mas integrações entre vários deles. Caso não esteja familiarizado com esses conceitos, o Blog é o lugar certo para cair de cabeça e descobrir mais sobre as entranhas dessa economia de APIs.Porém, se você começou a ler esse artigo, suponho que queira mesmo começar a fazer sua API, e queira ver exemplos, código e algumas dicas top sobre design e manutenção de APIs.Bom, você veio ao lugar certo. Vamos aprender a expor APIs na prática!No mundo do desenvolvimento de software, utilizar boas práticas é mais da metade do caminho para código mais limpos, com menos erros e maior facilidade de entendimento.E alguns materiais que podem te ajudar enquanto estuda os exemplos que darei nessa série de artigos podem ser os seguintes:

O que você vai aprender

Se você deu uma olhadinha nos conteúdos acima, viu que eles falam mais de conceitos e exemplos práticos do que de implementação.Portanto, aqui vamos às vias de fato.Quero abordar a parte prática e transformar conceitos em uma API que funciona!Vamos começar falando da Documentação de uma API, usando o Swagger, um framework completo para APIs.Logo em seguida, faremos uma visita à várias linguagens de programação, mostrando semelhanças, diferenças, vantagens e desvantagens de cada uma, em implementações de APIs RESTful.Veja as propriedades da arquitetura REST:

  • Client-Server: Cliente e servidor são separados e cada um possui sua responsabilidade bem definida;
  • Stateless: Cada requisição realizada contém todas as informações necessárias para executar o serviço;
  • Cacheable: Cliente e intermediários podem armazenar os responses;
  • Layered System: Os clientes não conseguem dizer se estão conectados diretamente no servidor ou em um intermediário;
  • Code on Demand: O servidor pode transferir código executável para o cliente;
  • Uniform Interface: Cada recurso precisa ser identificado por uma URI única.

(se não sabe exatamente o que é uma API RESTful, recomendo fortemente que assista ao Webinar de Design de APIs)Tendo um pouco de tudo isso em mente, podemos começar a pensar no Design da nossa API. Ela será uma API para um sistema de mudanças compartilhadas.Nossa lsita de decisões é a seguinte:

  • Nomear recursos, fazendo sentido para o negócio, garantindo que os nomes dos recursos devem estar sempre no plural e e evitando o uso de acentos ou caracteres especiais (exceto - ou _ );
  • Operações, sempre utilizando o nome do recurso e o id para executar operações como atualização, recuperação e exclusão
  • Usar os métodos HTTP adequadamente, com GET para buscas, POST para criação, PUT ou PATCH para alteração e DELETE para exclusão física e lógica.

Depois de parar para pensar em como será nossa API, e fazer seu design e documentação, vamos à nossa lista de linguagens de programação (em artigos futuros):

  • Rest na plataforma Java;
  • Rest com Node.js;
  • Rest e o PHP;
  • Rest na plataforma .Net.

Preparando o terreno

Nessa API vamos fazer o controle as transportadoras e clientes interessados em realizar um transporte.Sabendo que precisamos de URIs únicas para nossos recursos, chegou a hora de definir recursos, métodos (HTTP) e o caminho para acessarmos cada um desses recursos.Abaixo, para definir nossa API, vou especificar ações realizadas pela API, juntamente com o verbo HTTP que deverá ser usado e a URI onde o recurso está:

  1. Administrar transportadoras
  2. Listar todos as transportadoras
  3. Método: GET
  4. URI: /transportadoras
  5. Recuperar dados de uma transportadora por identificador
  6. Método: GET
  7. URI: /transportadoras/{transportadorasID}
  8. Atualizar dados de uma transportadora
  9. Método: PUT
  10. /transportadoras/{transportadorasID}
  11. Cadastrar nova transportadora
  12. Método: POST
  13. URI: /transportadoras
  14. Excluir uma transportadora (Exclusão lógica)
  15. Método: DELETE
  16. URI: /transportadoras/{transportadorasID}
  17. Administrar clientes
  18. Listar todos os clientes
  19. Método: GET
  20. URI: /clientes
  21. Recuperar dados de um cliente por identificador
  22. Método: GET
  23. URI: /clientes/{identificador}
  24. Atualizar dados de um cliente
  25. Método: PUT
  26. URI: /clientes/{identificador}
  27. Cadastrar novo cliente
  28. Método: POST
  29. URI: /clientes
  30. Excluir um cliente
  31. Método: DELETE
  32. URI: /clientes/{identificador}
  33. Administrar orçamentos
  34. Listar todos os orçamentos
  35. Método: GET
  36. URI: /orcamentos
  37. Recuperar dados de um orçamento por identificador
  38. Método: GET
  39. URI: /orcamentos/{identificador}
  40. Cadastrar um orçamento
  41. Método: POST
  42. URI: /orcamentos
  43. Atualizar parcialmente um orçamento
  44. Método: PUT
  45. URI: /orcamentos/{identificador}
  46. Excluir um orçamento
  47. Método: DELETE
  48. URI: /orcamentos/{identificador}
  49. Administrar as mudanças
  50. Cadastrar mudança
  51. Método: GET
  52. URI: /mudanca
  53. Reparar dados de uma mudança por identificador
  54. Método: GET
  55. URI: /mudanca/{identificador}
  56. Cadastrar uma mudança
  57. Método: PUT
  58. URI: /mudanca
  59. Atualizar parcialmente uma mudança
  60. Método: POST
  61. URI: /mudanca/{identificador}
  62. Excluir uma mudança
  63. Método: DELETE
  64. URI: /mudanca/{identificador}

A Documentação da API

Agora que já temos bem claro tudo que a API fará, está na hora de preparar a documentação.Esse artigo dá uma excelente introdução sobre o assunto. Mas como já comentei antes, é conceitual. Vamos ver na prática!A documentação e o código poderão ser encontradas no github da Sensedia: https://github.com/SensediaA ferramenta que usaremos para documentação é o Swagger. Ele é um framework para representar sua API RESTful e faz parte da Open API Specification.Com o Swagger, você é capaz de documentar de forma visual e interativa a sua API. Bem bacana!Para complementar o nosso conteúdo, eu sugiro uma lida no artigo Documentar é preciso, aqui no Blog da Sensedia e na especificação do swagger (https://swagger.io/specification/).Vamos explicar aqui os principais campos da estrutura do Swagger:

Campo Swagger

  • Tipo: string
  • Campo obrigatório. Define a versão da especificação do swager utilizado. Versão atual: 2.0.

Campo info

  • Tipo: title, description, termsOfService, license, version
  • Campo obrigatório. Informações de meta dado da API.

Campo host

  • Tipo: string
  • Host name ou IP da API.

Campo basePath

  • Tipo: string
  • Recurso raiz em que a API será acessada.

Campo schemes

  • Tipo: string
  • Este é o protocolo da API. Valores válidos: "http", "https", "ws", "wss".

Campo consumes

  • Tipo: string
  • MIME types que a API é capaz de consumir.

Campo produces

  • Tipo: string
  • MIME types de retorno da API.

Campo paths

  • Tipo: get, put, post, delete, options, head, patchm, parameters
  • Campo obrigatório. Definição de recursos e operações de uma API.

Campo definitions

  • Tipo: Object
  • Definição dos tipos utilizados nas APIs.

Campo parameters

  • Tipo: Object
  • Parâmetros para um determinado recurso e operação.

Campo responses

  • Tipo: Object
  • Objeto de retorna de um recurso e operação.

Campo securityDefinitions

  • Tipo: Object
  • Definições do esquema de segurança da API.

Campo security

Design feito?

Design e Documentação são as partes mais importantes da criação de uma API. Depois que são feitos (e se foram criados de forma adequada), o restante da criação da API fica bem mais simples!Veremos o que vem a seguir em posts futuros. Porém, repito: dedique bastante tempo nessa etapa inicial e o que virá depois será tranquilo.Você pode ver o arquivo Swagger da API do Hub Mudanças no Github da Sensedia: https://github.com/Sensedia/hubmudancasA partir do próximo post, podemos partir para o que os desenvolvedores estão aguardando ansiosamente: Code! Code! Code!Vamos discutir quais são as possibilidades de implementação de uma API utilizando Java e criar um exemplo prático.Nos vemos lá!Enquanto isso, que tal conferir na íntegra o nosso Webinar de Design de APIs? É um dos conteúdos mais elogiados da Sensedia! 1500 pessoas já assistiram =)

Conceitos não resolvem problemas. Se você quer exemplos para aprender a expor APIs na prática, veio ao lugar certo!

Obrigado pela leitura!

Voltar ao arquivo