This isn’t really a PHP-specific question but it’s probably the best place for it.
I need to create some RESTful services with PHP. It’s quite straightforward to do:
GET /foo[/:id] → Get all items or single item
POST /foo → Create a new item
PUT /foo/:id → Save an item
DELETE /foo/:id → Delete an item
That works great if you want to get all items or work with a single item. Is there a standard way to handle:
Searching
Creating, updating, deleting multiple items
For 1. I would use GET search (e.g. /foo[/:id]?category=6&page=1).
For 2. I would just pass an array of objects (JSON) by POST or PUT for creating and updating and an array of IDs by DELETE.
Does that sound about right?
As a general question in terms of the response is it standard to return a HTTP code and human-readable message each time?
For a successful POST and PUT do you return just a successful message and the insert ID (in the case of POST) — or do you return the full created resource? I’m guess the latter is better as the request may have been altered by the server (e.g. data is formatted).
I’d use /foo?category=6. Pagination is usually not the concern of web services (though you may restrict the number of returned resources). alternately you may opt in for offset/limit parameters.
no. web services are consumed by programmes, not humans. returning HTTP codes should be done, but the response should be (structurally) as consistent as possible across the web service.
if you return the resource, the web service consumer does not have to issue a separate request for the resource.
If pagination is not the concern of web services, what do you do if you have, say, 10m resources. Surely, you don’t GET them all and filter client side.
If you want to POST or PUT multiple resources is sending an array the way to do it?
Finally, for DELETE, I guess there is nothing to send back other than a HTTP code. If the resource has already been deleted or does exist would you think that deserves a 40x error?
Pagination should be a concern of the web service. Either use page/perpage or limit/offset combination. It doesn’t really matter as long as its consistent throughout the entirety of the api.
Using those methods you can also send content in the body of the request. An alternative method is sending json, xml, etc in the body. Their isn’t really a right or wrong approach as long as its consistent.
When an error occurs at the api level you should still send back some type of meaningful response that helps to diagnose and troubleshoot the issue.
Having said that when I build rest methods I typically send back an object with the following properties.
success boolean
msg string (feedback string for errors at api level)
data mixed (data coming back from the server ie. entities requested etc.)
total (for read/list) operations total number of items in set without pagination)