Best REST practises for adding and removing an element as opposed to deletion, and creation

[Aaron Caswell]

Hi Everybody,

I am sure this must have been answered well somewhere before, but I can't seem to find an answer that satisfies me...

I have a collection of 'fights', and a collection of 'fighters'. I want to be able to add and remove fighter to a fight restfully. Hence my resources and URI's are like so:

/fights/ -> all the fights that exist
/fights/{fightId} -> gives me fight fightId

The usual CRUD ops work on these resources as expected, like POST to /fights/ generates a new fight, etc.

Similarly,

/fighters/
/fighters/{fighterId}

does the same for fighters.

Now, it makes sense to me that a GET on the following should list all fighters scheduled for fightId:

/fights/{fightId}/fighters/

But what would be the advised way to add and remove fighters to/from a fight? To add should I POST to this URI with the id of an already existing fighter in the query string? Would I do a DELETE to /fights/{fightId}/fighters/{fighterId} to remove that fighter?

Maybe I am being picky, I don't know. My concern is that if I were to follow this approach then there is some inconsistency in DELETE's to /fighters/{fighterId} vs /fights/{fightId}/fighters/{fighterId}. One actually deletes an object from the DB whereas the other deletes an association, not the actual object it is talking about. However, the different URI's do establish the context of the operations, which maybe acceptable.

How rigid should these things be, or should I breakdown and make and add, remove verbs hanging off the end like this:

/fight/{fightId}/add?category=fight&id=fighterId

which seems complicated and yucky.

I hope I am clear-ish. Thank you in advance,

Aaron

[Mike Schinkel]

Hi Aaron,

Have you considered using PUT?  I'm not sure its the best approach, depends on your use case, but since you didn't mention it I though I'd bring it up If you can use PUT; others can advise if it's good or bad.

Here are what seem like some good articles on the subject:

http://www.markbaker.ca/2002/08/HowContainersWork/

http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/

http://stackoverflow.com/questions/630453/put-vs-post-in-rest

http://stackoverflow.com/questions/5686671/should-i-use-put-method-for-update-if-i-also-update-a-timestamp-attribute

Hope this helps.

-Mike

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group, send email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft?hl=en.
 
 

[Aaron Caswell]

Thank you Mike. Very helpful links,

This is a tournament system for arbitrary duels. I have to be able to generate a fight that will be scheduled for an arbitrary number of combatants. Generating a fight and fighters is no problem. My sticky use-case is that combatants may enlist or de-enlist themselves for the battle up until the fight starts.

Yes, I think a PUT probably does make sense for an add fighter operation. For example, supposing fighter 3 did not yet belong to fight 2, a PUT to /fights/2/fighters/3 would make sense in this scenario.

I guess I have been reluctant to do this looking at some of the various sources around the web that either propose creating a new element in such scenarios if one does not exist (wikipedia), or just plain error-ing out if performing a PUT to an element that does not exist (the apigee guys).

I have also seen patterns where an association resource is generated to indicate connections among objects. In this scenario, I believe, I would go:

/fights/2/associations/3

where 3 is the globally unique id for fighter 3. Now, deleting and, a post + put combination would make sense for as crud ops to connect the fighter to the fight. Deleting /associations/3 or fights/2/associations/3 both would delete the same thing, yet not delete fighter 3. The thing is it adds this weird associations resource that seems overly complicated. I hope I am making sense.

So far I am liking the PUT solution and permitting DELETEs to /fights/2/fighters/3 to just delete the association, not the actual fighter when applied to this particular path.

Thank you again,

Aaron

[Moore, Jonathan (CIM)]

As others have suggested, a PUT to /fighters/{fightId}/fight may be the simplest, especially if these are true duels (two max participants). If you want to support more (battle royale!), you could consider doing a PATCH to remove someone.

I wrote up some suggestions for how to handle "list" resources like this here:

http://codeartisan.blogspot.com/2012/08/hypermedia-programming-lists.html?m=1

Jon

........

Jon Moore

[Aaron Caswell]

That's a great approach.  I really like the idea of using PATCH'es to update lists. A new verb! By the way, your diff insertion method is a slick, general method to parametrize insertions. I am going to follow your blog for sure. Good stuff in there. Thank you,

Aaron

[Aaron Caswell]

By the way, regarding battle-royales, I was seeking a good solution for unbounded fighters joining a fight for the next version of this system: a tournament system for arbitrary rumbles :P