Best practices for REST-API models - rest

Question

I am working on a REST-API and have run into an architectural problem.
The model 'Book' represents a single book with properties and CRUD-based functions. It loads itself from a database via a read function.
However, what if I want to get all books in the database? The current book model does not cover this use case.
I have tried several approaches:
1.) A second model called 'Books'. It has a read function which returns a list of book objects.
2.) The model 'Book' itself has a readAll function which loads all books.
3.) The model 'Book' is non-functional, it only has properties. Instead a 'BookStorage' class loads the data and fills one/multiple models.
I am not satisfied with any of these approaches. Is there a best practice for this scenario?

Answer 1

1.) A second model called 'Books'. It has a read function which returns a list of book objects.
This is okay, but users and future developers on the project may be unclear on the fact that you have both Book and Books. So be sure to document the API, and comment the code. Also, you do need to consider input filters to limit down the results, or at least a method to page results. Google once estimated there were 130 million books, so you want to get all of them at once?
e.g. SERVER/Books/?skipRecords=0&limit=100
2.) The model 'Book' itself has a readAll function which loads all books.
This is not ideal as it violates the single responsibility principal. Mostly it just doesn't make a lot of sense in an OO situation to have a single book entity be able to list all of it's sibling entities.
e.g. SERVER/TheHobbit/readAll.... yuck.
3.) The model 'Book' is non-functional, it only has properties. Instead a 'BookStorage' class loads the data and fills one/multiple
models.
If you can expose these functional extension via the API, then that is an fine solution as well. It all comes down to documentation.
Maybe it ends up looking like this
e.g.
SERVER/BookStorage/GetAllBooks?skipRecords=0&limit=100
SERVER/BookStorage/GetBook?title=TheHobbit

Answer 2

3.) The model 'Book' is non-functional, it only has properties. Instead a 'BookStorage' class loads the data and fills one/multiple models.
This approach is similar to the Repository Pattern and is very common. The BookStorage would be a BookRepository with an interface like:
public interface IBookRepository
{
Book GetById(int id);
IEnumerable<Book> GetAll();
// Other methods for creating, updating and deleting books.
}
In your controller you would then have:
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();
// ...
}
}
If you want paging, you would add a filter like Get(int page = 0) and then depending on your page size, use something like bookRepository.GetAll().Skip(PAGE_SIZE * page).Take(PAGE_SIZE).
A model should not load itself as it would violate the Single responsibility principle.

Answer 3

A great resource when designing RESTful webservices is Martin Fowler's article Richardson Maturity Model.
To summarise for your book case:
use POST /book to create a book
use PUT /book to update a book
use GET /book?author=Shakespeare&year=1602&someOtherParam=someValue to find books
use GET /book/:id to retrieve the details of a particular book
use DELETE /book/:id to delete a certain book
Also you might want to follow the HATEOAS principles, so you'll need to include all relevant links for a book into a links property, so that clients of your API will not need to build their own link when they'll want to add/edit/find/delete a book.
Although simple at first sight, designing a good RESTful webservice is not that easy, however HATEOAS helps because url schema changes on the server side don't affect clients as they don't hardcode the URL's needed for the CRUD operations. All you need to do is provide a starting point, e.g. a base url where all contents can be discovered, and clients can start from there navigating through your webservice.

Answer 4

Read the CRUD Operations section here. You will find REST best practices to be followed when designing a REST API