ideal API routes

Question

I'm writing an api. To this point I've been using a route:

http://api.com/resource

and I pass in an action that I want to do to the resource within a json field and go from there. Is this an ideal or preferable situation from both a programmer and user perspective?

Or,

Would something like:

http://api.com/resource/action

be more useful, restful, right (take you pick). Or does it not matter at all? It works as it is, but I'm aiming for public consumption and I'd like to get any problems I'm unaware of with this out of the way before it gets more difficult to change.

Edit:

To add more detail the action I'm not concerned about is of GET, POST, etc. I have a route:

http://api.com/thing

This is a POST route, it creates a thing. Things aren't being stored in a database or anywhere at this point, so the thing created is immediately returned with the response. Users can specify that thing be returned painted a color: red, yellow, or green. From a user perspective, is it more useful to specify the color requirement as part of the post data above or to have routes like:

 http://api.com/thing/red

where posting to returns a red thing.

Answer 1

Basically, the action doesn't need to be specified (in the URL or in the data sent) as HTTP verbs, in a REST approach, are used to describe actions to perform on resources. So, your two solutions are not really "REST compliant". What you should do first is combining your route http://api.com/resources with some HTTP verbs in order to:

• Create a resource is: POST http://api.com/resources
• Read a resource is: GET http://api.com/resources/
• Update (replacing actually) a resource is: PUT http://api.com/resources/
• Delete a resource is: DELETE http://api.com/resources/

As usual, following conventions is better. Your two solutions are not ideal for a programmer with a taste for conventions and best practices. However, your second solution is readable and explicit. That means if you really want to choose between your two solutions, the second one seems better. But, if you want to update your API to follow more REST conventions, you should consider your resource as a real resource and use HTTP verbs.

I recommend you these two presentations about REST APIs:

• http://fr.slideshare.net/Wombert/designing-http-interfaces-and-restful-web-services-dpc2012-20120608
• https://speakerdeck.com/u/nicola/p/developing-restful-web-apis-with-python-flask-and-mongodb

You may be interested by this other question and the answer I gave: Resource and Action URI convention for REST.

Edit: according to your new question, send all data as post data, even your color. It will be more consistent. Why should it be different anyway? You should change the URI only if you describe different resources. If the color is just a property of a thing then you don't describe two resources and you should send the color with all other post data.