A True RESTful API | Help needed

Question

I know that a RESTful would have unified API and it treats everything as a resource (a noun, example a book, a product,...) and it can be applied with CRUD operations using HTTP Verbs (GET, PUT, POST, PATCH, DELETE,...)

I am aware of the fact of nouns & verbs.

Now, I am building a Web API that is managing the books and custom analytics of the books like,

1. Which books or categories are searched frequently?
2. Demand vs availability

ASP.Net Web API

BooksController - GET(Odata), PUT, POST, PATCH, DELETE

PagesController - GET(Odata), PUT, POST, PATCH, DELETE

BookAnalyticsController - GetFrequentBooks, GetFrequentCategories,...

PageAnalyticsController - GetFrequentPages, GetBookmarkedPages,...

I used Odata to query list by properties and select the properties as well. This will save duplicate counter-REST methods like GetBooksByCategory, GetBooksByYear, GetBooksByAuthor,..

Now, you know that BookAnalyticsController and PageAnalyticsController is going to have multiple HTTPGET verbs based on use-cases.

For Books or Pages controller, I can elegantly browse like

GET https://locahost/api/book

GET https://locahost/api/book/id

POST https://locahost/api/book BODY

PUT https://locahost/api/book/id BODY

PATCH https://locahost/api/book/id PARTIALBODY

For BookAnalytics,

GET https://locahost/api/bookanalytics/GetFrequentBooks

GET https://locahost/api/bookanalytics/GetFrequentCategories

IMO, it is kind of looking ugly. How would you make it pure RESTful API for analytics. Please suggest

Answer 1

Your RESTful API does not necessarily need to present a CRUD interface. Resources that are computed from other data do not need to support Create, Update or Delete operations, but they can still be presented with a Read interface (HTTP GET verb.)

So your structure in general looks nice, but you could improve the names somewhat.

https://gearheart.io/blog/restful-api-design-best-practices/ gives some reasonable naming recommendations. Two should be applied to your names:

• Use plural for nouns, so books instead of book
• Do not repeat Get in resource names, it is already indicated in the HTTP verb GET. The resource names GetFrequentBooks and GetFrequentCategories should better be frequent-books and frequent-categories (lowercase and hyphenated pluralized nouns.)