CODEWITHSUNDEEP
rest
starteleport
starteleport

Reputation: 1269

Creating new document (entity), adding it to collection

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/.

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?

Upvotes: 4

Views: 641

Answers (2)

creinig
creinig

Reputation: 1580

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.

Upvotes: 3

Khon Lieu
Khon Lieu

Reputation: 4365

Usually when I create a REST API, I use the singular form of the entity name, so it's 

api.company.com/item

From there if a client want's a particular item, they would do an HTTP GET

api.company.com/item/{id}

And usually you don't want the verb to be in the URL. so "item/new" is poor design. The standard HTTP methods should be sufficient (GET, POST, PUT, DELETE)

So for your case, I would recommend not doing "item/new" and just let the client do an HTTP POST to

api.company.com/item

If you're doing XML you give clients an XSD so they know what's required or not. If you're using JSON, it'll probably be documented somewhere.

As for enforcing the required "title" field, I would do validation of all new entities posted to your resource. I assume you have a domain model that the posted data gets mapped to. You can just do your validation and return a HTTP response with status 400, or if your API has custom error response use that.

Here's a resource I check out pretty often to remember the HTTP status codes and their meaning

Upvotes: 2

Related Questions