Criar uma API REST com Roteamento de Atributo no ASP.NET Web API 2
A API Web 2 dá suporte a um novo tipo de roteamento, chamado roteamento de atributo. Para obter uma visão geral do roteamento de atributos, consulte Roteamento de atributo na API Web 2. Neste tutorial, você usará o roteamento de atributos para criar uma API REST para uma coleção de livros. A API dará suporte às seguintes ações:
Ação | URI de exemplo |
---|---|
Obtenha uma lista de todos os livros. | /api/books |
Obtenha um livro por ID. | /api/books/1 |
Obtenha os detalhes de um livro. | /api/books/1/details |
Obtenha uma lista de livros por gênero. | /api/books/fantasy |
Obtenha uma lista de livros por data de publicação. | /api/books/date/2013-02-16 /api/books/date/2013/02/16 (formulário alternativo) |
Obtenha uma lista de livros de um autor específico. | /api/authors/1/books |
Todos os métodos são somente leitura (solicitações HTTP GET).
Para a camada de dados, usaremos o Entity Framework. Os registros do livro terão os seguintes campos:
- ID
- Título
- Gênero
- Data da publicação
- Preço
- Descrição
- AuthorID (chave estrangeira para uma tabela Authors)
Para a maioria das solicitações, no entanto, a API retornará um subconjunto desses dados (título, autor e gênero). Para obter o registro completo, o cliente solicita /api/books/{id}/details
.
Pré-requisitos
Visual Studio 2017 Community, Professional ou Enterprise Edition.
Criar o projeto do Visual Studio
Comece executando o Visual Studio. No menu Arquivo, selecione Novo e Projeto.
Expanda a categoriaVisual C#Instalado>. Em Visual C#, selecione Web. Na lista de modelos de projeto, selecione ASP.NET Aplicativo Web (.NET Framework). Nomeie o projeto como "BooksAPI".
Na caixa de diálogo Novo aplicativo Web ASP.NET , selecione o modelo Vazio . Em "Adicionar pastas e referências principais para", marque a caixa de seleção API Web . Clique em OK.
Isso cria um projeto esqueleto configurado para a funcionalidade da API Web.
Modelos de domínio
Em seguida, adicione classes para modelos de domínio. No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Modelos. Selecione Adicionar e , em seguida, classe. Nome da classe Author
.
Substitua o código em Author.cs pelo seguinte:
using System.ComponentModel.DataAnnotations;
namespace BooksAPI.Models
{
public class Author
{
public int AuthorId { get; set; }
[Required]
public string Name { get; set; }
}
}
Agora, adicione outra classe chamada Book
.
using System;
using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;
namespace BooksAPI.Models
{
public class Book
{
public int BookId { get; set; }
[Required]
public string Title { get; set; }
public decimal Price { get; set; }
public string Genre { get; set; }
public DateTime PublishDate { get; set; }
public string Description { get; set; }
public int AuthorId { get; set; }
[ForeignKey("AuthorId")]
public Author Author { get; set; }
}
}
Adicionar um controlador de API Web
Nesta etapa, adicionaremos um controlador de API Web que usa o Entity Framework como a camada de dados.
Pressione CTRL+SHIFT+B para criar o projeto. O Entity Framework usa reflexão para descobrir as propriedades dos modelos, portanto, requer um assembly compilado para criar o esquema de banco de dados.
No Gerenciador de Soluções, clique com o botão direito do mouse na pasta Controladores. Selecione Adicionare controlador.
Na caixa de diálogo Adicionar Scaffold , selecione Controlador da API Web 2 com ações, usando o Entity Framework.
Na caixa de diálogo Adicionar Controlador , em Nome do controlador, insira "BooksController". Marque a caixa de seleção "Usar ações do controlador assíncrono". Para Classe de modelo, selecione "Livro". (Se você não vir a Book
classe listada na lista suspensa, certifique-se de ter criado o projeto.) Em seguida, clique no botão "+".
Clique em Adicionar na caixa de diálogo Novo Contexto de Dados .
Clique em Adicionar na caixa de diálogo Adicionar Controlador . O scaffolding adiciona uma classe chamada BooksController
que define o controlador de API. Ele também adiciona uma classe chamada BooksAPIContext
na pasta Models, que define o contexto de dados para o Entity Framework.
Propagar o banco de dados
No menu Ferramentas, selecione Gerenciador de Pacotes NuGet e, em seguida, selecione Console do Gerenciador de Pacotes.
Na janela Console do Gerenciador de Pacotes, digite o seguinte comando:
Add-Migration
Esse comando cria uma pasta Migrações e adiciona um novo arquivo de código chamado Configuration.cs. Abra esse arquivo e adicione o código a Configuration.Seed
seguir ao método .
protected override void Seed(BooksAPI.Models.BooksAPIContext context)
{
context.Authors.AddOrUpdate(new Author[] {
new Author() { AuthorId = 1, Name = "Ralls, Kim" },
new Author() { AuthorId = 2, Name = "Corets, Eva" },
new Author() { AuthorId = 3, Name = "Randall, Cynthia" },
new Author() { AuthorId = 4, Name = "Thurman, Paula" }
});
context.Books.AddOrUpdate(new Book[] {
new Book() { BookId = 1, Title= "Midnight Rain", Genre = "Fantasy",
PublishDate = new DateTime(2000, 12, 16), AuthorId = 1, Description =
"A former architect battles an evil sorceress.", Price = 14.95M },
new Book() { BookId = 2, Title = "Maeve Ascendant", Genre = "Fantasy",
PublishDate = new DateTime(2000, 11, 17), AuthorId = 2, Description =
"After the collapse of a nanotechnology society, the young" +
"survivors lay the foundation for a new society.", Price = 12.95M },
new Book() { BookId = 3, Title = "The Sundered Grail", Genre = "Fantasy",
PublishDate = new DateTime(2001, 09, 10), AuthorId = 2, Description =
"The two daughters of Maeve battle for control of England.", Price = 12.95M },
new Book() { BookId = 4, Title = "Lover Birds", Genre = "Romance",
PublishDate = new DateTime(2000, 09, 02), AuthorId = 3, Description =
"When Carla meets Paul at an ornithology conference, tempers fly.", Price = 7.99M },
new Book() { BookId = 5, Title = "Splish Splash", Genre = "Romance",
PublishDate = new DateTime(2000, 11, 02), AuthorId = 4, Description =
"A deep sea diver finds true love 20,000 leagues beneath the sea.", Price = 6.99M},
});
}
Na janela Console do Gerenciador de Pacotes, digite os comandos a seguir.
add-migration Initial
update-database
Esses comandos criam um banco de dados local e invocam o método Seed para popular o banco de dados.
Adicionar classes DTO
Se você executar o aplicativo agora e enviar uma solicitação GET para /api/books/1, a resposta será semelhante à seguinte. (Adição de recuo para legibilidade.)
{
"BookId": 1,
"Title": "Midnight Rain",
"Genre": "Fantasy",
"PublishDate": "2000-12-16T00:00:00",
"Description": "A former architect battles an evil sorceress.",
"Price": 14.95,
"AuthorId": 1,
"Author": null
}
Em vez disso, quero que essa solicitação retorne um subconjunto dos campos. Além disso, quero que ele retorne o nome do autor, em vez da ID do autor. Para fazer isso, modificaremos os métodos do controlador para retornar um DTO (objeto de transferência de dados ) em vez do modelo EF. Um DTO é um objeto projetado apenas para transportar dados.
Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Adicionar | Nova Pasta. Nomeie a pasta como "DTOs". Adicione uma classe chamada BookDto
à pasta DTOs, com a seguinte definição:
namespace BooksAPI.DTOs
{
public class BookDto
{
public string Title { get; set; }
public string Author { get; set; }
public string Genre { get; set; }
}
}
Adicione outra classe chamada BookDetailDto
.
using System;
namespace BooksAPI.DTOs
{
public class BookDetailDto
{
public string Title { get; set; }
public string Genre { get; set; }
public DateTime PublishDate { get; set; }
public string Description { get; set; }
public decimal Price { get; set; }
public string Author { get; set; }
}
}
Em seguida, atualize a BooksController
classe para retornar BookDto
instâncias. Usaremos o método Queryable.Select para projetar Book
instâncias em BookDto
instâncias. Aqui está o código atualizado para a classe do controlador.
using BooksAPI.DTOs;
using BooksAPI.Models;
using System;
using System.Data.Entity;
using System.Linq;
using System.Linq.Expressions;
using System.Threading.Tasks;
using System.Web.Http;
using System.Web.Http.Description;
namespace BooksAPI.Controllers
{
public class BooksController : ApiController
{
private BooksAPIContext db = new BooksAPIContext();
// Typed lambda expression for Select() method.
private static readonly Expression<Func<Book, BookDto>> AsBookDto =
x => new BookDto
{
Title = x.Title,
Author = x.Author.Name,
Genre = x.Genre
};
// GET api/Books
public IQueryable<BookDto> GetBooks()
{
return db.Books.Include(b => b.Author).Select(AsBookDto);
}
// GET api/Books/5
[ResponseType(typeof(BookDto))]
public async Task<IHttpActionResult> GetBook(int id)
{
BookDto book = await db.Books.Include(b => b.Author)
.Where(b => b.BookId == id)
.Select(AsBookDto)
.FirstOrDefaultAsync();
if (book == null)
{
return NotFound();
}
return Ok(book);
}
protected override void Dispose(bool disposing)
{
db.Dispose();
base.Dispose(disposing);
}
}
}
Observação
Exclui os PutBook
métodos , PostBook
e DeleteBook
, porque eles não são necessários para este tutorial.
Agora, se você executar o aplicativo e solicitar /api/books/1, o corpo da resposta deverá ter esta aparência:
{"Title":"Midnight Rain","Author":"Ralls, Kim","Genre":"Fantasy"}
Adicionar atributos de rota
Em seguida, converteremos o controlador para usar o roteamento de atributo. Primeiro, adicione um atributo RoutePrefix ao controlador. Esse atributo define os segmentos de URI iniciais para todos os métodos nesse controlador.
[RoutePrefix("api/books")]
public class BooksController : ApiController
{
// ...
Em seguida, adicione atributos [Route] às ações do controlador, da seguinte maneira:
[Route("")]
public IQueryable<BookDto> GetBooks()
{
// ...
}
[Route("{id:int}")]
[ResponseType(typeof(BookDto))]
public async Task<IHttpActionResult> GetBook(int id)
{
// ...
}
O modelo de rota para cada método de controlador é o prefixo mais a cadeia de caracteres especificada no atributo Route . Para o GetBook
método , o modelo de rota inclui a cadeia de caracteres parametrizada "{id:int}", que corresponde se o segmento de URI contiver um valor inteiro.
Método | Modelo de rota | Exemplo de URI |
---|---|---|
GetBooks |
"api/books" | http://localhost/api/books |
GetBook |
"api/books/{id:int}" | http://localhost/api/books/5 |
Obter detalhes do livro
Para obter detalhes do livro, o cliente enviará uma solicitação GET para /api/books/{id}/details
, em que {id} é a ID do livro.
Adicione o método a seguir à classe BooksController
.
[Route("{id:int}/details")]
[ResponseType(typeof(BookDetailDto))]
public async Task<IHttpActionResult> GetBookDetail(int id)
{
var book = await (from b in db.Books.Include(b => b.Author)
where b.BookId == id
select new BookDetailDto
{
Title = b.Title,
Genre = b.Genre,
PublishDate = b.PublishDate,
Price = b.Price,
Description = b.Description,
Author = b.Author.Name
}).FirstOrDefaultAsync();
if (book == null)
{
return NotFound();
}
return Ok(book);
}
Se você solicitar /api/books/1/details
, a resposta terá esta aparência:
{
"Title": "Midnight Rain",
"Genre": "Fantasy",
"PublishDate": "2000-12-16T00:00:00",
"Description": "A former architect battles an evil sorceress.",
"Price": 14.95,
"Author": "Ralls, Kim"
}
Obter livros por gênero
Para obter uma lista de livros em um gênero específico, o cliente enviará uma solicitação GET para /api/books/genre
, em que gênero é o nome do gênero. (Por exemplo, /api/books/fantasy
.)
Adicione o método a seguir a BooksController
.
[Route("{genre}")]
public IQueryable<BookDto> GetBooksByGenre(string genre)
{
return db.Books.Include(b => b.Author)
.Where(b => b.Genre.Equals(genre, StringComparison.OrdinalIgnoreCase))
.Select(AsBookDto);
}
Aqui, estamos definindo uma rota que contém um parâmetro {genre} no modelo de URI. Observe que a API Web é capaz de distinguir esses dois URIs e encaminhá-los para métodos diferentes:
/api/books/1
/api/books/fantasy
Isso ocorre porque o GetBook
método inclui uma restrição de que o segmento "id" deve ser um valor inteiro:
[Route("{id:int}")]
public BookDto GetBook(int id)
{
// ...
}
Se você solicitar /api/books/fantasy, a resposta terá esta aparência:
[ { "Title": "Midnight Rain", "Author": "Ralls, Kim", "Genre": "Fantasy" }, { "Title": "Maeve Ascendant", "Author": "Corets, Eva", "Genre": "Fantasy" }, { "Title": "The Sundered Grail", "Author": "Corets, Eva", "Genre": "Fantasy" } ]
Obter livros por autor
Para obter uma lista de livros para um autor específico, o cliente enviará uma solicitação GET para /api/authors/id/books
, em que id é a ID do autor.
Adicione o método a seguir a BooksController
.
[Route("~/api/authors/{authorId:int}/books")]
public IQueryable<BookDto> GetBooksByAuthor(int authorId)
{
return db.Books.Include(b => b.Author)
.Where(b => b.AuthorId == authorId)
.Select(AsBookDto);
}
Este exemplo é interessante porque "livros" é tratado como um recurso filho de "autores". Esse padrão é bastante comum em APIs RESTful.
O bloco (~) no modelo de rota substitui o prefixo de rota no atributo RoutePrefix .
Obter livros por data de publicação
Para obter uma lista de livros por data de publicação, o cliente enviará uma solicitação GET para /api/books/date/yyyy-mm-dd
, em que yyyy-mm-dd é a data.
Aqui está uma maneira de fazer isso:
[Route("date/{pubdate:datetime}")]
public IQueryable<BookDto> GetBooks(DateTime pubdate)
{
return db.Books.Include(b => b.Author)
.Where(b => DbFunctions.TruncateTime(b.PublishDate)
== DbFunctions.TruncateTime(pubdate))
.Select(AsBookDto);
}
O {pubdate:datetime}
parâmetro é restrito para corresponder a um valor DateTime . Isso funciona, mas na verdade é mais permissivo do que gostaríamos. Por exemplo, esses URIs também corresponderão à rota:
/api/books/date/Thu, 01 May 2008
/api/books/date/2000-12-16T00:00:00
Não há nada de errado em permitir esses URIs. No entanto, você pode restringir a rota a um formato específico adicionando uma restrição de expressão regular ao modelo de rota:
[Route("date/{pubdate:datetime:regex(\\d{4}-\\d{2}-\\d{2})}")]
public IQueryable<BookDto> GetBooks(DateTime pubdate)
{
// ...
}
Agora, somente as datas no formato "yyyy-mm-dd" corresponderão. Observe que não usamos o regex para validar se temos uma data real. Isso é tratado quando a API Web tenta converter o segmento de URI em uma instância datetime . Uma data inválida, como '2012-47-99', não será convertida e o cliente receberá um erro 404.
Você também pode dar suporte a um separador de barras (/api/books/date/yyyy/mm/dd
) adicionando outro atributo [Route] com um regex diferente.
[Route("date/{pubdate:datetime:regex(\\d{4}-\\d{2}-\\d{2})}")]
[Route("date/{*pubdate:datetime:regex(\\d{4}/\\d{2}/\\d{2})}")] // new
public IQueryable<BookDto> GetBooks(DateTime pubdate)
{
// ...
}
Há um detalhe sutil, mas importante aqui. O segundo modelo de rota tem um caractere curinga (*) no início do parâmetro {pubdate}:
{*pubdate: ... }
Isso informa ao mecanismo de roteamento que {pubdate} deve corresponder ao restante do URI. Por padrão, um parâmetro de modelo corresponde a um único segmento de URI. Nesse caso, queremos que {pubdate} abrange vários segmentos de URI:
/api/books/date/2013/06/17
Código do controlador
Aqui está o código completo para a classe BooksController.
using BooksAPI.DTOs;
using BooksAPI.Models;
using System;
using System.Data.Entity;
using System.Linq;
using System.Linq.Expressions;
using System.Threading.Tasks;
using System.Web.Http;
using System.Web.Http.Description;
namespace BooksAPI.Controllers
{
[RoutePrefix("api/books")]
public class BooksController : ApiController
{
private BooksAPIContext db = new BooksAPIContext();
// Typed lambda expression for Select() method.
private static readonly Expression<Func<Book, BookDto>> AsBookDto =
x => new BookDto
{
Title = x.Title,
Author = x.Author.Name,
Genre = x.Genre
};
// GET api/Books
[Route("")]
public IQueryable<BookDto> GetBooks()
{
return db.Books.Include(b => b.Author).Select(AsBookDto);
}
// GET api/Books/5
[Route("{id:int}")]
[ResponseType(typeof(BookDto))]
public async Task<IHttpActionResult> GetBook(int id)
{
BookDto book = await db.Books.Include(b => b.Author)
.Where(b => b.BookId == id)
.Select(AsBookDto)
.FirstOrDefaultAsync();
if (book == null)
{
return NotFound();
}
return Ok(book);
}
[Route("{id:int}/details")]
[ResponseType(typeof(BookDetailDto))]
public async Task<IHttpActionResult> GetBookDetail(int id)
{
var book = await (from b in db.Books.Include(b => b.Author)
where b.AuthorId == id
select new BookDetailDto
{
Title = b.Title,
Genre = b.Genre,
PublishDate = b.PublishDate,
Price = b.Price,
Description = b.Description,
Author = b.Author.Name
}).FirstOrDefaultAsync();
if (book == null)
{
return NotFound();
}
return Ok(book);
}
[Route("{genre}")]
public IQueryable<BookDto> GetBooksByGenre(string genre)
{
return db.Books.Include(b => b.Author)
.Where(b => b.Genre.Equals(genre, StringComparison.OrdinalIgnoreCase))
.Select(AsBookDto);
}
[Route("~/api/authors/{authorId}/books")]
public IQueryable<BookDto> GetBooksByAuthor(int authorId)
{
return db.Books.Include(b => b.Author)
.Where(b => b.AuthorId == authorId)
.Select(AsBookDto);
}
[Route("date/{pubdate:datetime:regex(\\d{4}-\\d{2}-\\d{2})}")]
[Route("date/{*pubdate:datetime:regex(\\d{4}/\\d{2}/\\d{2})}")]
public IQueryable<BookDto> GetBooks(DateTime pubdate)
{
return db.Books.Include(b => b.Author)
.Where(b => DbFunctions.TruncateTime(b.PublishDate)
== DbFunctions.TruncateTime(pubdate))
.Select(AsBookDto);
}
protected override void Dispose(bool disposing)
{
db.Dispose();
base.Dispose(disposing);
}
}
}
Resumo
O roteamento de atributo oferece mais controle e maior flexibilidade ao projetar os URIs para sua API.