我应该使用哪个资源来保留我的API RESTFul？

Question

I'm building an API to allow the client of the API to send notifications to remind a user to update an Order status. So far, there are two notifications:

• when the user hasn't marked the order as received;
• when the user hasn't marked the order as done.

I want to build this API to make it simple to extend to other notifications related to the order, but keep a simple URI for the clients of this API. How can I define my resources in order to keep my API RESTFul?

I was thinking about having one of these structures:

Option 1 :

POST: /api/ordernotification/receive/{id}
POST: /api/ordernotification/complete/{id}

Option 2 (omit the status from the resource and post it instead) :

POST: /api/ordernotification/?id={id}&statusID={statusID}

EDIT

Option 2.1 (keeping an articulated URI, as suggested by @Jazimov) :

POST: /api/ordernotification/{statusID}/{id}. 

Which option is more appropriate? Is there any advantage that one option has over the other? Or are there any other option I haven't thought of?

Answer 1

If I understand you correctly, you have two types of ordernotifications : those for notifying receive and those for notifying complete . If those are two separate data models then I think nesting them is a good idea (ie a table called ReceiveOrderNotification and CompleteOrderNotification ). If that's the case then you may want to expose two different endpoints entirely, such as POST /api/receiveordernotification and POST /api/completeordernotification .

But I don't think that's the best you can do, given so many overlapping similarities there probably are between order notifications. Now, option 2 is more like a GET , since you're using query parameters, so with your first option let's collapse them into this:

POST: /api/ordernotification/

and then pass it some JSON data to create the notifications

{
    "orderId": "orderId",
    "userId": "userId",
    "prompt": "not marked received/not marked done"
}

I also removed the /{id} because when you POST you create a brand new thing and the id has not been created yet, usually. Even if the client is creating an id and sending it to the API it is a good practice to leave it open so your API can handle creating a new, unique resource in its own way.

This is RESTful is because a POST creates a resource ordernotification with certain data points. Your first option made actions a resource in themselves but that's probably not represented in any data model in your backend. To be as RESTful as possible, your API endpoints should represent the database domains (tables, collections, etc). Then you let your controllers choose what service methods to use given the data sent in the request. Otherwise REST endpoints expose all the logic up front and get to be a long list of unmaintainable endpoints.

Answer 2

I would go with something along these lines

POST /api/order/1234/notifications/not-received
POST /api/order/1234/notifications/not-completed

Which can later be accessed via

GET /api/order/1234/notifications/not-received
GET /api/order/1234/notifications/not-completed

Or

GET /api/order/1234/notification/8899

There's no real limitation on how semantically rich a URI can be, so you might as well take advantage of that and be explicit.

Answer 3

I think, to update status of already inserted records, your endpoint should be PUT instead of POST.

You can use

PUT: /api/ordernotification/:id/status/

with clients json data

 {
     "status": "your_status"
 }

according to request data, endpoint should update the record.