Creating new document (entity), adding it to collection
rest
Solution
Why first returning an empty item? I'd just let the client POST a new item (including all its properties) to /items/new instead. At least that's the way I remember it being done in Rails ;)
In any case, the additional returning of an empty item serves no use, adds an additional network roundtrip and potentially breaks the REST approach by splitting the "add" operation into "allocate" and "write contents".
If you want to do any uniqueness checks, UID generation etc that can be done just as well (or better) with one "add the complete item" operation.
Update : The confusion maybe comes from the fact that the rails controllers both act as REST API as well as controllers for the web UI. This means that some actions are useful in an API (that is used by some application / code) and some are needed because the presentation layer (used by a human) needs something it can call. I wouldn't really consider the "new" action to be useful in an API, but the user does need something he can call to get an empty form.
Problem
Suppose we have the collection `/items/` and we want to allow clients to add new items to this collection. Inspired by Rails, I've come to the following: we simply add resource `/items/new`, and the one who wants to add an item first issues `GET /items/new`, receiving empty entity (probably with some default values set), then fills the desired fields and issues `POST /items/`. - Is this approach good for true REST API? What could be improved/reworked? - If suddenly this approach is good (and if it's not, anyway): Suppose each item has the required field Title. It's probably not so good to return some default value in response to `GET /items/new`. What is better in this case? To return `null` Title and return an error when it's POSTed empty? To implement constructor-like logic for `new` resource, asking for required fields, say, in query string? Something else? Thank you. UPD. Just to clarify, using `new` is not about splitting "add" into "allocate" and "write contents" since no action on data store is done on `GET /items/new`. It's meant to be a way to achieve flexibility in entity design: rich client may dynamically render input fields according to what came in response to new. Does that make sense? Or the contract is to be fixed and we need to version the API for the changes like this?