No último artigo desta série, você aprenderá sobre as recomendações da API REST e exemplos de desenvolvimento do Java e Spring Web Services.
Ao desenvolver uma boa API REST, é importante ter bons microsserviços.
Como você desenvolve sua API REST? Quais são as melhores práticas?
Você aprenderá:
- Como desenvolver uma boa API REST?
- O que devo pensar ao desenvolver uma API REST?
- Quais são as melhores práticas para o desenvolvimento de serviços web RESTful?
API REST
Este é o último artigo de uma série de artigos sobre a API REST:
Use a primeira abordagem do consumidor
Quem usará seu serviço? Atendimento ao consumidor.
Você vê o serviço da perspectiva do consumidor?
- Se você estiver desenvolvendo uma API, seu consumidor pode entender sua API?
- Se você publicar seus recursos, o consumidor poderá encontrá-los e acessá-los?
- O consumidor pode entender seus URIs?
- Que tipo de serviço você oferece?
- É um aplicativo móvel ou web?
- Quais consumidores você espera e esses tipos de consumidores podem mudar no futuro?
- Se você estiver implementando algo como HATEOAS, pense em como seus clientes o usarão antes de implementá-lo.
- O mais importante é ter uma excelente documentação
- Facilite as coisas para que seus clientes economizem seu tempo.
- Quanto mais consumidores puderem fazer por conta própria, menos trabalho para você.
Sempre que você tiver uma discussão ou revisão de serviço, coloque os requisitos do cliente em primeiro lugar.
Use a primeira abordagem do contrato
O que é um contrato?
O criador do serviço da web é considerado
um provedor de serviços . Um aplicativo que usa um serviço da Web é um
consumidor do serviço .
Um contrato é um acordo entre um provedor e um consumidor sobre um serviço.
Para usar o serviço corretamente, o consumidor do serviço deve entender completamente o contrato. O contrato inclui detalhes de muitos aspectos do serviço, como:
- Como chamar um serviço da web?
- Que tipo de transporte é usado?
- Quais são as estruturas de solicitação e resposta?
Isso também é chamado de
definição de serviço .
Na primeira abordagem do contrato, você primeiro define um contrato de serviço e depois implementa apenas o serviço.
Primeiro contrato com WSDL
Por exemplo, ao definir serviços da web SOAP, você usa o WSDL para definir o contrato.
O WSDL determina quais são os pontos de extremidade do serviço, as operações que você publica e as estruturas de solicitação e resposta.
Contrato primeiro com Swagger / Open API
Quando você usa serviços da web RESTful, o Swagger é uma ferramenta popular para documentar seus serviços da web.
O Swagger permite determinar quais recursos você fornece como parte da sua API. Inclui os detalhes de cada operação, por exemplo, se usa XML, JSON ou ambos. Um esboço de resposta também está lá.
Ele também fornece informações detalhadas sobre os códigos de resposta que ele suporta. Você também pode ver que este recurso específico,
/ jpa / users :
suporta operação GET. De fato, ele também suporta a operação POST:
O esquema de resposta, se este recurso estiver disponível, será:
A definição do objeto Usuário está presente no contrato Swagger como:
Inclui atributos: data de
nascimento ,
identificação ,
nome e uma série de mensagens de postagens. Alguns campos também incluem um campo de descrição dentro deles.
Na primeira abordagem do contrato, antes de implementar o serviço, você manualmente ou usando o aplicativo cria a definição que o Swagger criou.
Benefícios da primeira abordagem do contrato
Usando a primeira abordagem do contrato, você pensa em seus clientes e em como eles podem usar esse serviço. Você não está inicialmente preocupado com os detalhes da implementação.
Se, no estágio inicial, você atribui grande importância à implementação, os detalhes técnicos penetram na definição do seu serviço.
Você precisa garantir que a definição do seu serviço não dependa da plataforma que você está usando, seja Java, .NET ou qualquer outro.
Definir padrões da organização para a API REST
Uma orientação importante para seus padrões organizacionais é o YARAS.
YARAS significa
ainda outro padrão de API RESTful . O YARAS fornece os padrões, diretrizes e convenções que devem ser seguidas ao desenvolver serviços da web RESTful. Ele dá recomendações para as seguintes coisas:
- Como você deve nomear seus serviços
- Como você deve estruturar sua solicitação e resposta
- Como você deve implementar filtragem, classificação, paginação e outras ações
- Como você deve abordar o versionamento
- Como você precisa abordar a documentação da API
Abordagem unificada para o desenvolvimento de serviços
Você precisa resolver muitos problemas complexos antes de começar a projetar serviços da web RESTful. Todas as opções acima, você precisa descobrir.
A liderança da sua organização não deseja que as equipes que lidam com recursos diferentes tenham abordagens diferentes para essas coisas.
Por exemplo, é indesejável para a Equipe A organizar o controle de versão com base em parâmetros de consulta e a Equipe B usar o controle de versão com base no URI.
Portanto, é importante que você tenha definido claramente os padrões organizacionais para sua abordagem aos serviços da web RESTful.
Personalização YARAS SOB necessidades organizacionais
O bom do YARAS é que ele pode ser personalizado para atender às necessidades específicas da organização. Por exemplo, você pode:
- Configure como devem ser os corpos de solicitação e resposta.
- Escolha um sistema de controle de versão específico
Como o YARAS possui uma cobertura bastante abrangente, você pode ter certeza de que não perdeu uma única decisão importante.
Escolhendo uma estrutura corporativa padrão da API REST
As estruturas típicas usadas para criar serviços da Web RESTful no mundo Java são Spring MVC, Spring REST e JAX-RS.
Se você criar um aplicativo de estrutura / arquétipo / referência específico da organização que atenda aos padrões comuns da organização na parte superior da plataforma API REST preferida, isso permitirá que as equipes adiram facilmente aos padrões comuns.
Os recursos típicos incluem:
- Estruturas de solicitação e resposta
- Tratamento de erros
- filtragem
- Pesquisar
- Versionamento
- Suporte para respostas falsas
- Hateoas
A estrutura padrão fornece uma abordagem unificada para projetar e implementar serviços em toda a organização.
Gerenciamento descentralizado da API REST
Crie um grupo de especialistas das equipes que criam a API REST e forme uma equipe de gerenciamento. A equipe é responsável por
- Melhorando os padrões da API REST
- Construindo / projetando sua estrutura de API REST
Uso generalizado de HTTP
Sempre que você pensar em serviços da web RESTful, pense em HTTP.
O HTTP possui todos os recursos que ajudam a criar excelentes serviços da web.
Use os métodos de solicitação HTTP corretos
Pense nos métodos de solicitação HTTP que você precisa usar. Ao pensar em implementar uma operação, determine o recurso no qual ela deve ser executada e localize o método de solicitação HTTP apropriado. Você recupera detalhes, cria algo, atualiza algo existente ou exclui um existente?
Usando métodos HTTP:
- GET para obter
- POST para criar
- PUT para atualizar
- DELETE para excluir
- PATCH para atualizações parciais
Use o status de resposta HTTP apropriado
Ao executar a operação, certifique-se de retornar o status de resposta correto.
Por exemplo, quando um recurso específico não for encontrado, não ative uma exceção do servidor. Em vez disso, envie o código de resposta apropriado em uma mensagem de resposta, como
404 .
Se realmente houver uma exceção do servidor, envie o código
500 de volta.
Se a validação falhar, envie o código para a solicitação inválida.
Foco no desempenho
Cada recurso pode ter várias representações - no formato XML ou JSON. O consumidor do serviço pode escolher a apresentação de sua escolha.
O serviço retorna 3 usuários quando enviamos uma solicitação GET. Nesse caso, obtemos a representação JSON do recurso
/ users .
Quando o consumidor não indica uma visualização preferida, usamos JSON.
O consumidor pode enviar um cabeçalho Aceitar para indicar a exibição.
O corpo da resposta agora tem conteúdo XML:
Use o plural
Sempre use o plural ao nomear recursos.
Vejamos um exemplo simples. Suponha que tenhamos um serviço que hospeda um recurso do usuário. A seguir, descreve como acessá-los:
- Criar usuário: POST / users
- Excluir usuário: DELETE / users / 1
- Obter todos os usuários: GET / users
- Obter um usuário: GET / users / 1
A preferência de vários usuários em relação ao usuário torna o URI mais legível.
- Por exemplo, se usarmos / user em vez de / users para obter, GET / user não passará a mensagem correta para o leitor.
Crie boa documentação
Os consumidores precisam entender como fazer o melhor uso do serviço, e a melhor maneira de ajudá-los é criar uma boa documentação.
Os serviços web SOAP podem usar a funcionalidade WSDL, enquanto os serviços web RESTful têm opções Swagger (agora o padrão de documentação da API aberta).
A escolha de um formato é apenas uma parte da criação de uma boa documentação. O que também é importante é o fornecimento da quantidade certa de informações para ajudar o consumidor.
A documentação deve estar completa e incluir os seguintes pontos:
- O que é uma estrutura de solicitação e resposta?
- Como um consumidor deve se autenticar?
- Quais são os limites de uso?
- Indique todos os tipos de mensagens de resposta e códigos de status correspondentes que podem ser esperados do serviço.
Crie um portal de documentação comum da API REST
Seria útil ter um portal de documentação da API REST comum para toda a organização. Dê uma olhada em um desses portais:
Esse portal reúne todos os recursos disponíveis na organização. Ter uma interface de usuário como a interface do usuário do Swagger terá seus benefícios adicionais. Usando a interface do usuário do Swagger, você pode ver a documentação em mais detalhes:
Isso pode ser usado mesmo por usuários não técnicos. As informações fornecidas aqui incluem:
- Formato de resposta esperado
- Tipo de conteúdo
- Códigos de resposta suportados
O formato da documentação no estilo de uma solicitação / resposta ativa também pode ser interessante.
Suporte de versão
O controle de versão implica grande complexidade para um serviço da web. Manter várias versões diferentes do mesmo serviço da web é muito difícil. Tente evitar isso sempre que possível.
No entanto, em certos cenários, o controle de versão é inevitável.
Vamos começar examinando um serviço de exemplo. Suponha que inicialmente definimos um serviço que tenha a classe
PersonV1 da seguinte maneira:
Esta versão da classe não leva em consideração que um nome pode ter muitas subseções, como nome e sobrenome. Verifique isto:
A segunda versão da classe de origem foi atualizada para corrigir esta anomalia:
Não podemos transferir imediatamente todo o serviço para usar o
PersonV2 ! Pode haver outros consumidores que aguardam respostas no formato
PersonV1 .
É aqui que o controle de versão é necessário.
Vejamos agora as opções que temos para o controle de versão desses dois recursos.
Usando URIs diferentes
Temos uma opção - usar URIs diferentes para esses recursos diferentes. No código do exame abaixo, usamos os URIs
v1 / person e
v2 / person para distingui-los:
Se você executar uma solicitação GET para o recurso
v1 / person :
Você receberá informações correspondentes à
v1 . Para outro recurso:
Usando o parâmetro de consulta
O segundo método de controle de versão usa o parâmetro de consulta:
No URI
/ person / param , se enviarmos o parâmetro com
versão = 1 , retornamos um recurso do tipo
PersonV1 :
Para o mesmo URI, o parâmetro com
versão = 2 retorna um recurso do tipo
PersonV2 :
Esse método é chamado de controle de versão usando parâmetros de consulta.
Usando um cabeçalho (cabeçalho)
Outra maneira de fazer isso é o controle de versão, especificando um título. Aqui, usamos um cabeçalho chamado
X-API-VERSION e marcamos o URI como
/ person / header . Quando o valor do cabeçalho é
1 , um recurso do tipo
PersonV1 é retornado :
Quando seu valor é
2 , um recurso do tipo
PersonV2 é recuperado:
Usamos o atributo no cabeçalho da solicitação para executar o controle de versão para nós.
Usando o cabeçalho Accept
O método final para criar versões usa o cabeçalho Accept. Se o consumidor incluir as informações da primeira versão no cabeçalho Accept da solicitação GET, o seguinte recurso será retornado:
Caso contrário, um recurso do tipo
PersonV2 será retornado :
Esse método de controle de versão é denominado
Accept Header Versioning ou
Media Type Versioning , pois os tipos MIME geralmente são o conteúdo do cabeçalho Accept.
Comparação de métodos de controle de versão
Até agora, vimos quatro tipos de métodos nas versões:
- Usando URIs diferentes
- Usando o parâmetro de consulta
- Uso do cabeçalho
- Usando aceitar cabeçalho / tipo de mídia
Qual é o melhor? A verdade é que não há uma resposta única para essa pergunta. O fato é que diferentes gigantes da Internet apadrinham diferentes tipos de versões.
- Usando diferentes URIs - Twitter
- Usando parâmetro de consulta - Amazon
- Usando um cabeçalho - Microsoft
- Usando aceitar cabeçalho / tipo de mídia - GitHub
Você precisa avaliar essas quatro opções de acordo com suas necessidades específicas. Há vários fatores importantes a serem considerados:
- Poluição de URI : controlando versões usando URIs e parâmetros de consulta, acabamos poluindo o espaço de URI. Isso ocorre porque adicionamos prefixos e sufixos às principais strings do URI. O controle de versão usando um cabeçalho evita isso.
- Uso indevido de cabeçalhos HTTP . No caso de controle de versão usando cabeçalhos e tipo de mídia, os cabeçalhos HTTP são mal utilizados porque não foram originalmente destinados ao controle de versão.
- Armazenamento em cache : um recurso é identificado por seu URI. No entanto, se você não usar um URI para determinar sua versão, mas usar um mecanismo baseado em cabeçalho, as informações da versão não poderão ser armazenadas em cache. Se o cache HTTP for importante para você, use o controle de versão com base em um URI ou em um parâmetro de solicitação.
- Executabilidade de solicitação do navegador : o controle de versão com base no título e no tipo de mídia requer ferramentas como o Postman. No entanto, se os consumidores de serviços não forem tecnicamente esclarecidos, é preferível usar o controle de versão com base em um parâmetro de consulta ou URI.
- Documentação da API : você também precisa pensar em como deseja documentar suas APIs. O controle de versão baseado no URI e no parâmetro de consulta é mais fácil de documentar do que os outros dois tipos de controle de versão.
Entenda que não existe uma solução ideal única!
Pense no tratamento de erros
Quando um consumidor envia uma solicitação a um serviço, é importante que ele receba a resposta correta. Sempre que algo der errado, é importante enviar uma resposta apropriada.
Quando um consumidor solicita um recurso inexistente
Se enviarmos uma solicitação GET para procurar um usuário existente, obteremos a seguinte resposta:
Se você está procurando um usuário inexistente:
O que você recebe é o status
404 Não encontrado . Este é um bom tratamento de erros, pois determina corretamente que o recurso não foi encontrado e não retorna um erro no servidor.
Vamos agora enviar uma solicitação GET para um URI inexistente:
Como você pode ver, você obtém
404 status de resposta
Não encontrado . Um URL inválido indica um recurso que não existe.
Status de resposta importantes
- 200 - sucesso
- 404 - recurso não encontrado
- 400 - solicitação inválida (por exemplo, erro de validação)
- 201 - criado
- 401 - não autorizado (se a autenticação falhar)
- 500 - erro no servidor
Detalhes do erro no corpo da resposta
Isso ajuda se você tiver uma estrutura de exceção padrão ao desenvolver seu serviço.
Para erros específicos, estruturas de resposta específicas podem ser devolvidas ao consumidor, e esse pode ser o padrão em toda a organização. Verifique se a resposta ao erro também é legível para os consumidores, sem confusão.
Usando o Swagger ou a documentação da API aberta
O Swagger fornece um dos formatos de documentação mais populares para serviços web RESTful. Hoje, ele é suportado por várias organizações e é usado em um grande número de serviços. Aqui, examinamos dois aspectos principais do Swagger:
- Formato de documentação do Swagger
- Interface do usuário do Swagger, que permite examinar a documentação do Swagger de uma maneira visualmente conveniente
Documentação do Swagger
Dê uma olhada no seguinte Swagger JSON:
No nível superior, isso se parece muito com a definição de WSDL. Possui vários atributos importantes:
- host : onde o serviço está localizado
- basePath : o caminho em que o serviço está localizado
- consome : quais solicitações são aceitas
- produz : Quais tipos de respostas são gerados
- caminhos : vários recursos disponíveis Nesse caso, você tem vários tipos de recursos na lista:
Ao examinar a documentação do Swagger, você pode identificar rapidamente os recursos disponíveis, operações suportadas e operações relacionadas a cada recurso:
O recurso
/ users suporta operações
GET e
POST . Para
GET, você pode ver os tipos de solicitação e resposta suportados. Você também vê vários tipos de respostas:
Observe que, para a resposta
200, o circuito também é chamado de matriz do
usuário .
O usuário faz parte da seção de
definições na parte inferior do documento:
O Swagger é completamente independente da tecnologia usada para implementar um serviço da web RESTful. Ah, tudo é baseado em JSON.
Apresentando a interface do usuário do Swagger
A interface do usuário do Swagger é uma ótima interface do usuário que é muito útil para visualizar a documentação do Swagger para o serviço da web RESTful.
Dê uma olhada na captura de tela abaixo:
Observe que selecionamos uma versão específica do serviço da web para visualizar sua documentação. Aqui está a mesma tela com mais detalhes:
Quando vamos para a página inicial, ele descreve os recursos listados:
Você também pode ver o conjunto de operações suportadas para URLs de recursos:
Ao clicar na operação GET de um recurso específico, você obtém seus detalhes:
Você pode ver que o esquema Os modelos são descritos visualmente. Os atributos birthDate , id , links , nome e postagens também são exibidos. Você também pode executar uma consulta de exemplo e visualizar a resposta:
Usando ferramentas Swagger (Open API Standard)
O melhor do Swagger são as muitas ferramentas disponíveis. Dê uma olhada no seguinte serviço que usamos anteriormente para explicar o controle de versão: A seguir, veja a documentação gerada automaticamente para este serviço: O
Swagger tem suporte para a abordagem de contrato primeiro e a abordagem de código primeiro.Sobre esta questão, há um vídeo do autor .Sumário
Neste artigo, analisamos as práticas recomendadas para criar e projetar serviços da Web RESTful.Leitura adicional
Seja o melhor em sua API REST!Desenvolvendo APIs REST