Primeiras aulas do curso APIs Rest com Asp.NET Core 2.1 Parte 3: padronizando a API

APIs Rest com Asp.NET Core 2.1 Parte 3: padronizando a API

Resiliência ante mudanças - Introdução

E aí pessoal, tudo bem? Bem vindo novamente, obrigado por ter escolhido continuar nessa aventura aqui, agora a parte três deste curso. E nessa parte a gente vai voltar nossos olhos para a API, de novo para uma API REST. E eu quero mostrar duas coisas para vocês.

Primeiro tem um link aqui de um manual da Microsoft sobre REST API, com algumas dicas e orientações sobre como uma API REST deve se comportar, segundo a Microsoft. Então a gente vai usar isso aqui pra evoluir a nossa API.

Então aqui tem tabela de conteúdo, algumas coisas a gente já fez na parte 1, só que outras coisas ainda precisam ser feitas. Quais são elas: como é que a gente vai conseguir versionar, como é que você versiona uma API, tá dizendo aqui que há uma maneira que você tem que fazer isso. Como fazer, a gente vai ver no curso.

Como é que a gente lida com coleções muito grandes? A gente tem que aplicar paginação, tem que aplicar filtros, tem que aplicar ordenação nessa coleção. Vamos ver como é que a gente faz isso.

A nossa API não é prova de falha, então a gente precisa se comportar e tratar os erros de uma maneira consistente.

Outro passo é a gente aprender a documentar a nossa API, pra que os desenvolvedores que estão consumindo nossa API consigam adotá-la com muito mais rapidez e facilidade.

A gente vai ver que, quanto melhor a nossa API tiver documentada, melhor será a adoção da sua API. Se você quer fazer uma API que muita gente utilize, você precisa cuidar da sua documentação.

A gente vai chegar ao final desse curso, dessa segunda parte, e concluir esse curso com uma API documentada mais ou menos assim.

Então a gente tem a documentação, inclusive com a possibilidade de você fazer a autorização e testar a sua API, nessa própria ferramentinha, que não foi criada por mim, isso aqui vem de um pacote e tudo mais.

Então a gente vai ver como é que a gente coloca isso aqui na nossa API. Beleza? Tranquilo? Ficou animado? Ficou curioso?

Resiliência ante mudanças - Resiliência diante de mudanças

Fala aí pessoal, tudo bem?

Então, agora nossa API já tem clientes que estão a consumindo. E com isso a responsabilidade da gente, enquanto desenvolvedor dessa API, aumentou. A gente não pode mais fazer qualquer tipo de alteração na API porque isso pode impactar os clientes.

Por exemplo: vou abrir aqui o código do controlador de livros, do recurso livros, e vou mudar aqui no método recuperar, onde é entregue um livro como recurso aqui na minha API, eu vou fazer uma alteração simples aqui: vou alterar o retorno - deixar comentado porque vou voltar depois - do tipo livro API para um tipo livro. Uma alteração simples, eu acho que não vai ter nenhum impacto pros outros clientes, eu posso imaginar isso.

Então, vamos ver. Agora vou rodar a API. Rodei a API. Deixa eu ver se a autenticação tá rodando, também tá rodando já. Agora eu vou rodar a aplicação WEB, tem que fazer o login. Tá funcionando. Então não teve nenhum tipo de impacto? Será? Vamos ver o detalhe de um livro? Olha isso que aconteceu.

Então imagina o cara que está usando a aplicação web, se coloca no lugar dele. Ele tá usando a aplicação web normalmente, e aí um belo dia tava tudo funcionando, a gente viu isso na aula anterior, a gente fez todos os testes, incluiu, fez o CRUD. E um belo dia ele vai tentar ver o detalhe de um livro e toma esse erro aí.

E repare que este erro não é um erro que indica que houve uma mudança. É um erro que você, quando analisar, então você vai precisar de um pouco mais de tempo para analisar isso para descobrir que houve uma mudança na API, e essa mudança impactou no seu cliente, quebrou o seu cliente.

Então a responsabilidade agora aumenta quando você começa a ter clientes consumindo a sua API, você não pode mais fazer qualquer tipo de mudança. Gente, não é só uma mudança que quebre o cliente que a gente vai se preocupar. Existem mudanças no comportamento da sua API.

A gente vai ver mais para frente como implementar paginação nas coleções de recursos que a gente tem, coleção de livros. E isso vai fazer com que a gente altere o comportamento, vai tudo continuar funcionando, na verdade não, mas a gente vai continuar retornando uma coleção de livros, só que agora uma coleção paginada. Então é um subconjunto do total de livros que existe no banco de dados.

Então o cliente da API tava consumindo com a expectativa de pegar todos os livros e ele mesmo fazer algum tipo de processamento em cima daquilo. Agora não, agora ele vai receber um subconjunto. Quem foi que avisou ele sobre essa mudança? Então é uma mudança no comportamento.

Então pergunte-se, você como desenvolvedor da API: Será que os clientes vão continuar confiando em mim se eu ficar fazendo esse tipo de mudança, sem nenhum tipo de comunicação, sem nenhum tipo de tratamento? E o que a gente vai ver é que a gente precisa se preocupar com isso.

Voltando nosso papo, a gente tinha falado lá no começo do curso, lá no primeiro vídeo, onde eu mostrei que a gente vai adequar nossa API segundo os guidelines da Microsoft. A Microsoft tem, justamente, uma orientação para esse tipo de problema. Um problema em que você tem que: ao mesmo tempo que deixar a sua API resistente, estável, para que os clientes não quebrem, não tenham uma mudança de comportamento; você também tem que garantir que a sua API evolua.

Eu, como agilista, acredito que os times têm que estar sempre abertos às mudanças. Então, também a API tem que estar evoluindo por questões de negócio, por questões de performance, por questões de otimização, e evoluindo em todo sentido. Então como é que eu consigo equilibrar isso, equilibrar garantir estabilidade pros clientes e continuar evoluindo minha API?

Então vamos olhar aqui pro guideline da Microsoft e nós vamos descobrir que eles orientam nesse sentido. Aqui na parte de documentação no guideline existe uma parte específica para isso, que tá aqui no capítulo 12, sobre versionamento. E a primeira frase que tem aqui, é o seguinte: "Todas as APIs aderentes à essa guideline devem, obrigatoriamente, suportar versionamento explícito."

Por quê? Por que: "É crítico que os clientes possam contar com a estabilidade do serviço com o tempo, mas também é crítico que os serviços possam adicionar funcionalidades e fazer mudanças." Ou seja, evoluir. Então tá aqui escrito, negrito e tudo mais, que a gente deve suportar versionamento.

Quais são os formatos de versionamento? Tá aqui no guideline também, vou até aumentar aqui o foco. São dois tipos de formatos sugeridos pela Microsoft no guideline dela: um formato embutido no caminho da requisição. Por exemplo: a versão já aparece na própria URI do recurso, no caso aqui versão 1.0. Ou então, segundo formato, a versão vai estar disponível através de um parâmetro na query string.

Então nessa aula eu vou mostrar para vocês como que a gente vai implementar esses dois tipos de formato. Vamo lá?

Resiliência ante mudanças - Versionamento na URI

Então gente, antes de eu começar a implementar aqui o versionamento, eu quero que vocês tenham consciência do seguinte: agora nossa API vai suportar duas versões: versão 1, que é a atual; e a versão 2, justamente para poder receber as mudanças e a evolução da API a partir de agora. Então a versão 1 vai ser usada pelo nosso cliente, nossa aplicação WEB. Então vamos lá.

Na prática, o que que eu pretendo fazer aqui? Deixa eu abrir aqui o meu slide, fazer tudo pra vocês verem que aqui é tudo ao vivo.

Então que que eu quero fazer? Vou colocar aqui uma caixa de texto pra mostrar pra vocês que eu quero agora que a minha API suporte o seguinte tipo de URI. Ela tá atendendo no http://localhost:5000/api/livros/{id}, por exemplo. Então agora isso aqui não vai mais rolar. Vou até botar aqui em vermelho, não é mais assim. Como é que vai ser agora? http://localhost:5000/api/v1.0/livros/{id}. Esse aqui é um cara que a gente vai começar a suportar. Como eu falei que são duas versões então tá aqui, versão 2.0: http://localhost:5000/api/v2.0/livros/{id}

Então tô negritando aqui as mudanças para vocês enxergarem as diferenças. Esse cara aqui é vermelho, esse cara aqui não é vermelho. Deixa eu aumentar um pouquinho mais pra vocês enxergarem mais.

Então a gente vai fazer agora a implementação de versionamento na URI dos recursos da gente. A nossa aplicação WEB vai consumir a nossa API através desta URL, a versão 1.0. E a gente vai começar a evoluir a nossa API, a partir daqueles guidelines, a partir da versão 2.

Pra pegar um livro, cujo identificador é id, o que que eu preciso fazer? Vamos lá no Visual Studio. Já tô aqui no controlador de livros, o que eu preciso fazer é chegar nesse controlador LivrosController aqui. Esse controlador aí, ele é o controlador que vai atender a versão 1.0.

Então o que que eu tenho que fazer gente? Eu vou aqui na minha rota e coloco a versão. Se eu abrir agora o Postman e testar alguma requisição para pegar essa API. Ah é 6000 né? Foi mal gente, aqui é 6000. As coisas são ao vivo aqui.

Então aqui no Postman, se eu tentar fazer aqui API de 6000, http://localhost:6000/api/livros, e apertar o send, agora eu vou começar a tomar 401 porque eu ainda não modifiquei, eu não rodei novamente a minha API.

Beleza, rodei 6000, se eu tentar rodar agora Postman vai acontecer um 404, não tá mais acontecendo 401 porque ele não tá achando essa rota aqui: http://localhost:6000/api/livros. Agora é http://localhost:6000/api/v1.0/livros. Aí vou ter um 401. Então ele chegou lá, e aí rodou o Middleware de autorização do ASP.NET Core e eu não tenho autorização.

Então eu vou pegar um token aqui, vou passar ele dentro do meu cabeçalho de autorização, vou mandar o send e vou obter a coleção de livros. Se eu quiser um livro específico, 1009, eu tô pegando esse livro aqui.

Percebam que nessa versão aqui, versão 1.0, eu ainda tô com aquela modificação onde eu tô retornando o livro, o tipo livro. Então vamos fazer essa modificação aqui, porque eu não quero quebrar os clientes que estão consumindo a versão 1.0.

Ctrl+F5, vou voltar pro Postman, dar um send. O token continua válido. E agora eu peguei apenas o livro.

Reparem que a imagem de capa agora tem a URI. Tá até errada, porque também tem que botar a versão 1.0 aqui. Se eu clicar aqui e ele vai tentar rodar esse cara. Enfim, vocês já entenderam, não vou fazer isso agora não.

Então agora eu tô atendendo a versão 1.0. Vou criar uma nova requisição de GET. Mas eu quero também atender a versão 2.0. Apertar o send aqui, 404. Então que que eu tenho que fazer gente? Pra agora ter uma versão 2.0? O que eu tenho que fazer é criar uma nova classe de controller. Vou criar aqui uma nova classe de controller. Na verdade eu vou criar uma classe mesmo: adicionar, classe.

Qual o nome dessa classe? Repare que a rota é livros. Então eu teria que ter uma classe chamada LivrosController também? E aí, como é que vou fazer? São classes que têm o mesmo nome. A gente já aprendeu lá no começo, na Orientação a Objetos e .NET, que a gente, pra poder ter classes com o mesmo nome, usa namespaces diferentes.

É uma ideia, é uma solução que eu posso ter aqui: criar uma classe LivrosController com namespace diferente. Mas eu vou fazer um pouquinho diferente, eu vou criar uma classe com o nome Livros2Controller.

Deixa eu ver se o namespace ListaLeitura.Api.Controllers, vou usar o mesmo namespace: ListaLeitura.Api.Controllers. Esse cara aqui herda de ApiController. Não. De ControllerBase e ele tem anotação de ApiController. Então ele tem uma notação ApiController. Tem uma notação também pra rota e aqui é que eu vou dizer que a rota será api/v2.0/livros.

Que mais que tinha ali? Eu também tenho que autorizar esse meu controlador adicionando aqui no uses. Vou limpar aqui os namespaces desnecessários.

E o código que tá aqui gente? Gente o código vai ser quase igual ao código que eu tenho no meu LivrosController. Copy and paste.

Mas Daniel, isso tá certo? Dar copy and paste? Galera eu tô agora suportando duas versões. E essas duas versões estão, por enquanto, iguais. Eu posso, de repente, pensar em usar a orientação a objetos, usar a herança, usar composição. De repente alguma interface para me ajudar. Posso fazer tudo isso pra melhorar o código e diminuir a duplicação. Mas tenham a consciência de que em algum momento você vai ter o ônus de suportar essas duas versões. Que façam as mesmas coisas, parecido, com algumas mudanças nas versões posteriores.

Então, por enquanto, eu vou deixar esse código aqui duplicado. Na verdade eu vou deixar esse código duplicado até o fim do curso, mas você poderia pensar em melhorar isso para ajudar a sua manutenção. Só que em algum momento você vai ter que garantir, você vai ter esse ônus de ter que ficar suportando essas duas versões.

Aqui acho que tá faltando o namespace do link. Acho que agora não tem mais erro nenhum.

Então o Livros2Controller, no método recuperar, ele não vai retornar um model.ToApi, ele vai retornar um livro. Então o Livros no método recuperar, na versão 1.0, ele retorna um Livro API. E o Livros2Controller retorna um livro. É uma mudança muito simples, que não vai fazer diferença nenhuma, mas tem impacto lá nos nossos clientes que estão consumindo.

Então agora eu vou compilar aqui e a minha expectativa é que o Postman agora consiga atender essa rota. Já tá dizendo que não está autorizado, então significa que ele chegou, ele bateu lá. Vou colocar agora o token de autenticação. Vou mandar o send.

E agora eu tenho as duas versões sendo atendidas para o recurso livros. Percebam que eu fiz isso apenas para o controller livros. Eu tenho que fazer para todos os recursos que eu tiver. Mas eu fiz apenas para mostrar pra vocês como é que eu implemento versionamento na URL, com mais um segmento na URL, ou URI, do meu recurso.

Então o que eu fiz foi usar a anotação chamada Route e lá eu coloquei na mão a versão. Um deles tá mostrando a capa desse jeito e o outro está mostrando a capa desse jeito.

Então essa é a ideia de você implementar versionamento. Só que vocês perceberam que eu fiz isso na unha. Eu coloquei o número da versão fixo, hardcoded diretamente na rota do meu controlador aqui. Inclusive esse controlador teve até o livros, também, como valor fixo aqui.

Então antes da gente passar para o próximo vídeo, antes de você apertar o play no próximo vídeo, eu quero que você reflita: Quais seriam os problemas que eu teria, especificamente de versionamento, se eu colocar a versão diretamente na rota, na unha?

Então pensa aí: Quais problemas eu tenho para versionamento quando eu faço versionamento na unha?

Te espero no próximo vídeo com as respostas. Abraço.

Sobre o curso APIs Rest com Asp.NET Core 2.1 Parte 3: padronizando a API

O curso APIs Rest com Asp.NET Core 2.1 Parte 3: padronizando a API possui 161 minutos de vídeos, em um total de 48 atividades. Gostou? Conheça nossos outros cursos de .NET em Programação, ou leia nossos artigos de Programação.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

Aprenda .NET acessando integralmente esse e outros cursos, comece hoje!

  • 998 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

Premium

  • 998 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$75
à vista R$900
Matricule-se

Premium Plus

  • 998 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$100
à vista R$1.200
Matricule-se

Max

  • 998 cursos

    Cursos de programação, UX, agilidade, data science, transformação digital, mobile, front-end, marketing e infra.

  • Certificado de participação

    Certificado de que assistiu o curso e finalizou as atividades

  • App para Android e iPhone/iPad

    Estude até mesmo offline através das nossas apps Android e iOS em smartphones e tablets

  • Projeto avaliado pelos instrutores

    Projeto práticos para entrega e avaliação dos professores da Alura com certificado de aprovação diferenciado

  • Acesso à Alura Start

    Cursos de introdução a tecnologia através de games, apps e ciência

  • Acesso à Alura Língua

    Reforço online de inglês e espanhol para aprimorar seu conhecimento

12X
R$120
à vista R$1.440
Matricule-se
Procurando planos para empresas?
Acesso por 1 ano
Estude 24h/dia onde e quando quiser
Novos cursos toda semana