Restful HTTP API pattern

Question

I am designing a Restful HTTP API and have a design question.

In my application users should be able to suggest item creations.

Then I can either approve or disapprove them.

I wonder what the best VERB+URL pattern for this would be.

Example 1:

POST|GET|PUT|DELETE /items

A user POST a new item and I can either PUT it to "approved" from "pending" or DELETE it.

Here I must use GET /items?status=approved to get all approved items and GET /items?status=pending to get all pending items. Perhaps GET /items would get me all the approved ones by default.

But I don't get how I can prevent users from PUTting it to approved state.

or

Example 2:

POST|GET|PUT|DELETE /item_creation_suggestions

A user POST a new item suggestion and I can either approve by DELETE:ting it and do a POST /items or just DELETE it.

Here /items and /item_creation_suggestions are two separate collections. I just have to delete the suggestions and create the items when approving.

This makes it simple to protect my app from unauthorized access. I can just protect my /items with authorization, while /item_creation_suggestions could be used by anyone.

But this doesn't seem very Restful?

The same goes for when users are suggesting items updates and deletions and I either approve or disapprove them.

I am very new at Restful design so all feedback and suggestions would be appreciated!

deceze deceze · Accepted Answer · 2012-06-13T09:44:25

The first one sounds good.

POST /items should create a new item and probably return a 202 Accepted status.
GET /items should return all approved items.
GET /items?status=pending should return pending items to users with the right permission.
PUT /items/[id] with a request body that designates a new status to change the status.
DELETE /items/[id] to delete the item.

In the end you need to decide what makes the most sense for your API, but the above sounds generally reasonable.

Restful HTTP API pattern

2 Answers