- Se você precisasse desenvolver um sistema desktop, como você o faria? Para criar uma janela no windows, você precisaria utilizar as APIs do Win32. - No linux, há o X.Org e o Wayland. Você gostaria que sua aplicação fosse multiplataforma, mas para isso você teria que escrever códigos diferentes que utilizariam cada API de cada sistema operacional. Você poderia pesquisar uma biblioteca ou framework que facilita esse processo, abstraindo os detalhes internos de cada API nativa dos sistemas operacionais em uma única API, como o Qt. Seu progama, então, utiliza este framework para mostrar uma interface, que por sua vez, internamente, utiliza as APIs nativas do sistema operacional onde o seu software está sendo executado. Já os sistemas operacionais utilizam as APIs do seu driver de vídeo para exibir as janelas no seu monitor, do controlador USB para ler o teclado e mouse, entre outros. Ou seja, com APIs podemos criar várias camadas de abstração. Todo o ambiente em um computador é composto por softwares comunicando-se uns com os outros, utilizando estas abstrações, através de APIs. + Se você precisasse desenvolver um sistema desktop, como você o faria? Para criar uma janela no sistema operacional Windows, você precisaria utilizar as APIs do Win32. + No Linux, para fazer a mesma coisa, você precisaria utilizar as APIs há o X.Org ou do Wayland. + Naturalmente, cada sistema operacional diferente possui APIs diferentes para criar interfaces gráficas. + Porém, você gostaria que sua aplicação fosse multiplataforma, mas para que isso aconteça, você teria que escrever códigos diferentes que utilizariam cada API de cada sistema operacional. + Você poderia pesquisar uma biblioteca ou framework que facilita esse processo, abstraindo os detalhes internos de cada API nativa dos sistemas operacionais em uma única API. + Seu progama, então, utiliza este framework para mostrar uma interface, que por sua vez, internamente, utiliza as APIs nativas do sistema operacional onde o seu software está sendo executado. + Já os sistemas operacionais por sua vez utilizam as APIs do seu driver de vídeo para exibir a interface no seu monitor, as APIs do controlador USB para ler eventos de teclado e mouse, entre outros. + Ou seja, com APIs podemos criar várias camadas de abstração. Todo o ambiente em um computador é composto por softwares comunicando-se uns com os outros, utilizando estas abstrações, através de APIs.
@@ -150,4 +160,365 @@ Response: "titulo": "Contos da Palma da Mão", "autor": "Yasunari Kawabata" }`} + +
+ E se quiséssemos cadastrar um livro, como poderíamos definir um endpoint que realizaria esta ação? +
+ +{`Request:
+POST /livros
+
+{
+ "isbn": "9780262510875",
+ "titulo": "Structure and Interpretation of Computer Programs",
+ "autor": "Gerald Jay Sussman"
+}
+
+Response:
+201 Created
+{
+ "isbn": "9780262510875",
+ "titulo": "Structure and Interpretation of Computer Programs",
+ "autor": "Gerald Jay Sussman"
+}`}
+ O verbo POST em uma requisição indica que desejamos inserir um recurso. No nosso caso, POST /livros indica que queremos criar um novo registro de livro.
+ Note que enviamos na requisição os dados do livro que desejamos inserir.
+
+ Se quisermos agora editar este mesmo livro que acabamos de inserir, podemos utilizar uma requisição com verbo PUT:
+
{`Request:
+PUT /livros/9780262510875
+
+{
+ "isbn": "9780262510875",
+ "titulo": "Structure and Interpretation of Computer Programs, 2nd ed.",
+ "autor": "Harold Abelson, Gerald Jay Sussman, Julie Sussman"
+}
+
+Response:
+200 Ok
+{
+ "isbn": "9780262510875",
+ "titulo": "Structure and Interpretation of Computer Programs, 2nd ed.",
+ "autor": "Harold Abelson, Gerald Jay Sussman, Julie Sussman"
+}`}+ Assim como no endpoint que obtém os dados de um livro, este também recebe na url o dado que identifica o registro, para indicar qual livro queremos editar. +
+ +
+ Comumente utiliza-se o verbo POST para criar, e o verbo PUT para editar. Uma diferença conceitual entre os dois verbos é que o POST é utilizado em operações que não são idempotentes.
+ Idempotência é uma propriedade de uma operação que define que a aplicação sucessiva da mesma operação não altera o estado do sistema. Por exemplo, se você mandar a mesma requisição PUT para editar um livro várias vezes seguidas,
+ com exatamente os mesmos dados, o estado daquele registro de livro manterá-se exatamente igual.
+ Já no POST, enviar várias requisições idênticas, com os mesmos dados, geraria vários registros de livros diferentes, pois cada requisição representa uma inserção (ou então, um erro de validação de dados seria retornado, por exemplo, informando que já existe
+ um livro com o mesmo ISBN cadastrado).
+
+ Por fim, para remover um livro, podemos utilizar o verbo DELETE:
+
{`Request:
+DELETE /livros/9788574481371
+
+Response:
+204 No Content`}
+ Este endpoint também recebe o dado que identifica o livro, assim definimos qual registro queremos remover. Normalmente, endpoints com verbo DELETE não possuem corpo na requisição, e têm respostas vazias.
+
Definindo os endpoints na API
+ ++ Temos então que os endpoints que precisamos implementar são: +
+ +-
+
GET /livrospara obter todos os livros no sistema;
+ GET /livros/{`{isbn}`}para obter um único livro, identificado pelo seu ISBN;
+ POST /livrospara inserir um novo livro;
+ PUT /livros/{`{isbn}`}para editar um livro;
+ DELETE /livros/{`{isbn}`}para remover um livro.
+
+ Vamos traduzir esta especificação para o código. Abra seu projeto, no arquivo Program.cs. No exemplo anterior, deixamos este arquivo assim:
+
{`var builder = WebApplication.CreateBuilder(args);
+
+var app = builder.Build();
+
+app.MapGet("/", () =>
+{
+ string[] saudacoes = ["Olá!", "こんにちは", "Привет", "Ողջույն"];
+
+ return saudacoes[Random.Shared.Next(saudacoes.Length)];
+});
+
+app.Run();`}
+ Definimos um endpoint GET / que responde com uma mensagem aleatória. Vamos utilizar a mesma sintaxe para definir os outros endpoints. Mas antes, vamos criar, neste mesmo arquivo, uma classe que irá representar um livro.
+
{`var builder = WebApplication.CreateBuilder(args);
+
+var app = builder.Build();
+
+app.MapGet("/", () =>
+{
+ string[] saudacoes = ["Olá!", "こんにちは", "Привет", "Ողջույն"];
+
+ return saudacoes[Random.Shared.Next(saudacoes.Length)];
+});
+
+app.Run();
+
+public class Livro
+{
+ public string? Isbn { get; set; }
+ public string? Titulo { get; set; }
+ public string? Autor { get; set; }
+};`}
+ Adicione esta classe no fim do arquivo. Todos os campos são do tipo string?. O ? após o tipo determina a nulabilidade daquela propriedade - ou seja, determina se a propriedade pode receber valores nulos.
+ Desta forma, o compilador consegue te auxiliar gerando avisos quando você faz uma referência a uma variável que pode ser nula sem antes verificá-la, o que, se acontecesse, geraria um erro em tempo de execução.
+
+ Agora, abaixo do MapGet("/", ...), escreva:
+
{`app.MapGet("/", () =>
+{
+ ...
+});
+
+// Obtém uma lista com os livros registrados.
+app.MapGet("/livros", () =>
+{
+ return new Livro[]
+ {
+ new()
+ {
+ Isbn = "9780262510875",
+ Titulo = "Structure and Interpretation of Computer Programs",
+ Autor = "Gerald Jay Sussman"
+ },
+ new()
+ {
+ Isbn = "9780131103627",
+ Titulo = "C Programming Language: ANSI C Version",
+ Autor = "Dennis Ritchie, Brian Kerningham"
+ },
+ new()
+ {
+ Isbn = "9780134190440",
+ Titulo = "The Go Programming Language",
+ Autor = "Brian Kerningham"
+ }
+ };
+});
+
+app.Run();
+
+public class Livro
+{
+...`}
+ Esta nova chamada para MapGet cria um endpoint GET /livros que responde com um array fixo de livros. Vamos utilizar
+ este array apenas para testarmos a chamada deste endpoint.
+
Testando o endpoint
+ +
+ Na estrutura de arquivos do seu projeto, deve haver um arquivo chamado Biblioteca/Biblioteca.http. Se não houver, crie-o. Em seguida,
+ substitua o conteúdo deste arquivo pelo seguinte:
+
{`@url = http://localhost:5000
+
+### Obtém uma lista de livros
+
+GET {{url}}/livros
+Accept: application/json`}+ Em seguida, instale a extensão REST Client no seu VSCode. +
+ +
+ Agora, volte em Biblioteca/Biblioteca.http, note que algumas opções adicionais estão sendo exibidas pelo VSCode.
+
+ Agora deve aparecer uma opção Send Request acima da linha GET {`{{url}}`}/livros. Execute o seu projeto, em seguida volte neste arquivo e clique nesta opção. Se tudo der certo,
+ uma requisição GET /livros será enviada para sua aplicação, e a resposta será exibida no lado direito da IDE.
+
+ Volte para o Program.cs. Vamos criar um POST agora:
+
{`// Cria um novo livro.
+app.MapPost("/livros", (Livro livro) =>
+{
+ return livro;
+});`}
+ MapPost cria um novo endpoint que responde ao verbo POST. Tanto no MapGet quanto no MapPost, o segundo argumento passado para o método é uma função anônima (ou função lambda).
+ Uma função anônima é, basicamente, uma função que não possui nome, e que pode ser referenciada em uma variável, passada como parâmetro para outras funções, e invocada desta forma.
+ No caso destes métodos de mapeamento de endpoints, esta função anônima passada é a função que será executada quando o endpoint for solicitado. Os argumentos dessa função são as entradas da requisição (parâmetros de URL, corpo da requisição),
+ e o valor de retorno é a resposta que deve ser devolvida ao cliente.
+
+ No caso deste MapPost que acabamos de escrever, note que há um argumento do tipo Livro. Isto indica para o framework que nosso endpoint deve receber dados que podem ser estruturados em um objeto
+ do tipo Livro. Como estamos apenas testando, nosso endpoint não fará nada além de retornar o mesmo livro que recebemos como entrada.
+
+ Execute o projeto (se já estiver executando, reinicie-o), e altere o seu Biblioteca.http:
+
{`@url = http://localhost:5000
+
+### Obtém uma lista de livros
+
+GET {{url}}/livros
+Accept: application/json
+
+### Cria um novo livro
+
+POST {{url}}/livros
+Accept: application/json
+Content-Type: application/json
+
+{
+ "isbn": "9780321741769",
+ "titulo": "The C# Programming Language",
+ "autor": "Anders Hejlsberg"
+}`}
+ Adicionamos uma nova linha POST {`{{url}}/livros`}. Cada linha abaixo desta representa um cabeçalho, o Accept e o Content-Type.
+ O Content-Type indica para o servidor o tipo de recurso que estamos enviando. Como estamos enviando um JSON, o Content-Type deve ser application/json
+ (valores de Content-Type são mimetypes).
+
+ Logo abaixo dos cabeçalhos, definimos o corpo da requisição que vamos enviar. Cada campo deste JSON é representado por um campo da classe Livro no nosso código.
+ O framework irá realizar a leitura deste JSON e a sua conversão em um objeto automaticamente.
+
+ Agora, experimente executar esta requisição, e observe a saída. +
+ +
+ Para criar um PUT, a sintaxe é a mesma, porém utilizando MapPut:
+
{`// Edita um livro.
+app.MapPut("/livros/{isbn}", (string isbn, Livro livro) =>
+{
+ return new { editando = isbn, dados = livro };
+});`}
+ A url que definimos agora possui um parâmetro definido por "{`{isbn}`}". Isto significa que este pedaço da
+ url delimitado por chaves pode assumir qualquer valor, por exemplo, PUT /livros/A, PUT /livros/B, etc.
+
+ Reinicie o projeto. Assim como no POST e no GET, altere o Biblioteca.http e teste a execução do endpoint:
+
{`### Edita um livro
+
+PUT {{url}}/livros/9780321741769
+Accept: application/json
+Content-Type: application/json
+
+{
+ "isbn": "9780321741769",
+ "titulo": "The C# Programming Language",
+ "autor": "Anders Hejlsberg, Mads Torgensen"
+}`}
+ Agora, só falta o GET /livros/{`{isbn}`} e o DELETE /livros/{`{isbn}`}:
+
{`// Obtém os dados de um livro individual.
+app.MapGet("/livros/{isbn}", (string isbn) =>
+{
+ return new Livro() { Isbn = isbn };
+});
+
+// Remove um livro.
+app.MapDelete("/livros/{isbn}", (string isbn) =>
+{
+ return Results.NoContent();
+});`}
+ Reinicie o projeto, altere o Biblioteca.http, e teste estes endpoints:
+
{`### Obtém um livro individual
+
+GET {{url}}/livros/9780321741769
+Accept: application/json
+
+### Remove um livro
+
+DELETE {{url}}/livros/9780321741769
+Accept: application/json`}+ Certifique-se de que você consegue executar todos estes endpoints sem nenhum erro. + Nas próximas etapas, iremos fazer a conexão do projeto com um banco de dados para que possamos implementar de fato os endpoints, + inserindo, modificando e consultando os dados. +
+ ++ Se estiver com dificuldades, o código fonte do projeto até agora pode ser baixado aqui. +
+