Рекомендации для моделей REST-API

Question

Я работаю над REST-API и столкнулся с проблемой архитектуры.

модель «Книга» представляет собой одну книгу со свойствами и функциями CRUD основе. Он загружается из базы данных с помощью функции чтения.

Однако, что если я хочу, чтобы получить все книги в базе данных? Текущая модель книги не охватывает этот вариант использования.

я пытался несколько подходов:

1.) вторая модель под названием 'Книга'. Он имеет функцию чтения, которая возвращает список объектов книги.

2.) Модель «Книга» сама по себе имеет функцию ReadAll которая загружает все книги.

3.) Модель «Книга» не является функциональным, он имеет только свойство. Вместо этого класс BookStorage загружает данные и заполняет одну или несколько моделей.

Я не удовлетворен ни одним из этих подходов. Существует ли наилучшая практика для этого сценария?

Answer 1

1.) Вторая модель называется 'Книга'. Он имеет функцию чтения, которая возвращает список объектов книги.

Это нормально, но пользователи и будущие разработчики проекта могут быть неясны в связи с тем, что у вас есть книга и книги. Поэтому обязательно задокументируйте API и прокомментируйте код. Кроме того, вам необходимо рассмотреть входные фильтры, чтобы ограничить результаты, или, по крайней мере, метод результатов страницы. Google однажды оценил, что было 130 миллионов книг, так что вы хотите получить все сразу?

например. SERVER/Книги /? SkipRecords = 0 & предел = 100

2.) Модель 'Книга' сама по себе имеет функцию ReadAll которая загружает все книги.

Это не идеальный вариант, поскольку он нарушает принцип единой ответственности. В основном это просто не имеет особого смысла в ситуации с ОО, чтобы иметь единственную книжную сущность, которая могла бы перечислить все ее дочерние сущности.

например. SERVER/TheHobbit/readAll .... yuck.

3.) Модель «Книга» нефункциональна, она обладает только свойствами. Вместо этого класс BookStorage загружает данные и заполняет одну или несколько моделей . Если вы можете предоставить эти функциональные расширения через API, то это тоже прекрасное решение. Все сводится к документации.

Может быть, это заканчивает тем, что, как это

например

SERVER/BookStorage/GetAllBooks? SkipRecords = 0 & предел = 100

SERVER/BookStorage/GetBook? Название = TheHobbit

Answer 2

3.) Модель «Книга» нефункциональна, она обладает только свойствами. Вместо этого класс BookStorage загружает данные и заполняет одну или несколько моделей.

Этот подход похож на Repository Pattern и очень распространен. BookStorage будет BookRepository с интерфейсом типа:

public interface IBookRepository 
{ 
    Book GetById(int id); 
    IEnumerable<Book> GetAll(); 
    // Other methods for creating, updating and deleting books. 
} 

В контроллере вы бы тогда:

public class BooksController: ApiController 
{ 
    private readonly IBookRepository _bookRepository; 

    public BooksController(IBookRepository bookRepository) 
    { 
     _bookRepository = bookRepository; 
    } 

    [Route("api/books/{id}")] 
    public IHttpActionResult Get(int id) 
    { 
     var book = _bookRepository.GetById(id); 

     // ... 
    } 

    [Route("api/books")] 
    public IHttpActionResult Get() 
    { 
     var books = _bookRepository.GetAll(); 

     // ... 
    } 
} 

Если вы хотите подкачки, необходимо добавить фильтр, как Get(int page = 0), а затем в зависимости от вашего размер страницы, используйте что-то вроде bookRepository.GetAll().Skip(PAGE_SIZE * page).Take(PAGE_SIZE).

Модель не должна загружаться, поскольку она нарушает Single responsibility principle.

Answer 3

Отличный ресурс при проектировании веб-сервисов RESTful - статья Мартина Фаулера Richardson Maturity Model.

Суммируя для book случая:

• использования POST /book создать книгу
• использовать PUT /book обновить книгу
• использование GET /book?author=Shakespeare&year=1602&someOtherParam=someValue найти книги
• использование GET /book/:id для извлечения деталей конкретная книга
• использовать DELETE /book/:id, чтобы удалить определенную книгу

Кроме того, вы можете следовать HATEOAS принципам, так что вам необходимо включить все соответствующие ссылки на книги в links собственность, так что клиенты вашего API не нужно будет строить свою собственную связь, когда они «Я хочу добавить/отредактировать/найти/удалить книгу.

Хотя простую на первый взгляд разработку хорошего веб-сервиса RESTful не так просто, однако HATEOAS помогает, поскольку изменения схемы URL-адресов на стороне сервера не влияют на клиентов, поскольку они не требуют жесткого кодирования URL-адресов, необходимых для операций CRUD. Все, что вам нужно сделать, это обеспечить отправную точку, например. базовый url, где все содержимое может быть обнаружено, и клиенты могут начать с него, перемещаясь через ваш веб-сервис.

Answer 4

Прочтите раздел CRUD Operations здесь. При разработке API REST вы найдете рекомендации по REST, которые должны соблюдаться.