Question

I’m implementing a RESTfull API to talk to AWS RDS, security_groups resource supports the typical CRUD verbs. When it comes to “authorize” and “revoke” i’m not sure what’s the best practice, which one do you think is best?

Custom action, params in url

PUT agifog:3000/rds/security_groups/:security_group/authorize?ec2name='default'&ec2owner='0123456789'

Custom action, passing params

PUT agifog:3000/rds/security_groups/:security_group/authorize
{
    "ec2name": "default"
    "ec2owner": "0123456789"
}

Standard update

PUT agifog:3000/rds/security_groups/:security_group
{
    "operation": "authorize"
    "ec2name": "default"
    "ec2owner": "0123456789"
}

Answer 1

The second seems the most RESTful. You’ve got a resource (security group) and a custom action (authorize) that will respond to your request’s verb (PUT).

PUT agifog:3000/rds/security_groups/:security_group/authorize
{
    "ec2name": "default"
    "ec2owner": "0123456789"
}

and similarly:

PUT agifog:3000/rds/security_groups/:security_group/revoke

(NOTE: I’d probably prefer a POST for the above if it will be generating a session or some other authentication data/token.)

For comparison, if you were interested in updating the attributes of that resource, you’d want to do something like:

PUT agifog:3000/rds/security_groups/:security_group
{
    "some_attr1": "some_val"
    "some_other_attr": "some_val"
}

In which case the PUT implies that it is an UPDATE to this resource.