A True RESTful API | Help needed
https://softwareengineering.stackexchange.com/questions/403472
-
06-03-2021 - |
题
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,
- Which books or categories are searched frequently?
- 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/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
解决方案
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 ofbook
- Do not repeat
Get
in resource names, it is already indicated in the HTTP verb GET. The resource namesGetFrequentBooks
andGetFrequentCategories
should better befrequent-books
andfrequent-categories
(lowercase and hyphenated pluralized nouns.)