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 são APIs – Parte 2: Como uma API funciona;
• Webinar de Design de APIs RESTful (um dos nosso conteúdos mais baixados);
• O que é uma Estratégia API First;
• Ebook de Blocos de Construção para Exposição de APIs.

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
3. Listar todos as transportadoras
4. Método: GET
5. URI: /transportadoras
7. Recuperar dados de uma transportadora por identificador
8. Método: GET
9. URI: /transportadoras/{transportadorasID}
11. Atualizar dados de uma transportadora
12. Método: PUT
13. /transportadoras/{transportadorasID}
15. Cadastrar nova transportadora
16. Método: POST
17. URI: /transportadoras
19. Excluir uma transportadora (Exclusão lógica)
20. Método: DELETE
21. URI: /transportadoras/{transportadorasID}
22. Administrar clientes
24. Listar todos os clientes
25. Método: GET
26. URI: /clientes
28. Recuperar dados de um cliente por identificador
29. Método: GET
30. URI: /clientes/{identificador}
32. Atualizar dados de um cliente
33. Método: PUT
34. URI: /clientes/{identificador}
36. Cadastrar novo cliente
37. Método: POST
38. URI: /clientes
40. Excluir um cliente
41. Método: DELETE
42. URI: /clientes/{identificador}
43. Administrar orçamentos
45. Listar todos os orçamentos
46. Método: GET
47. URI: /orcamentos
49. Recuperar dados de um orçamento por identificador
50. Método: GET
51. URI: /orcamentos/{identificador}
53. Cadastrar um orçamento
54. Método: POST
55. URI: /orcamentos
57. Atualizar parcialmente um orçamento
58. Método: PUT
59. URI: /orcamentos/{identificador}
61. Excluir um orçamento
62. Método: DELETE
63. URI: /orcamentos/{identificador}
64. Administrar as mudanças
66. Cadastrar mudança
67. Método: GET
68. URI: /mudanca
70. Reparar dados de uma mudança por identificador
71. Método: GET
72. URI: /mudanca/{identificador}
74. Cadastrar uma mudança
75. Método: PUT
76. URI: /mudanca
78. Atualizar parcialmente uma mudança
79. Método: POST
80. URI: /mudanca/{identificador}
82. Excluir uma mudança
83. Método: DELETE
84. 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

• Tipo: Security Requirement Object
• Declaração da segurança conforme definido no securityDefinitions.

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 =)