REST design : Action compare two object

[Erimei]

Hi API Crafters,

I am wondering what would be the best approach regarding a REST API where I need to provide the user REST for compare different between roles.

I was thinking of:

GET  .../rolemgmt/compare/{role1}/with/{role2}     

GET .../rolemgmt/compare/{role1,role2}              // This approach allow me compare more than two roles. 

GET .../rolemgmt/roles/{role1}/compare/{role2}

GET .../rolemgmt/roles?compare={role1, role2}  // This approach allow me compare more than two roles. 

What you think about it? Maybe you have others proposition. 

Thanks,

Erimei

[darrel...@gmail.com]

Hi Erimei,

This is a scenario where the resources you are trying to access are not hierarchical  so using query parameters makes the most sense.

The URI template could look like this[1],

GET .../rolemgmt/comparison{?roles}

and the expanded URL could look like this  

GET .../rolemgmt/comparison?roles=role1,role2,role3

If you prefer to fully expand the query parameters you can use

GET .../rolemgmt/comparison{?role*}

and the expanded URL would look like 

GET .../rolemgmt/comparison?role=role1&role=role2&role=role3

Darrel

[1] URI Template spec https://tools.ietf.org/html/rfc6570

Sent from Surface

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Andrew Braae]

I find it hard to visualize what the response would look like when comparing more than two roles (partially equal? a and b equal, and c and d equal, but a not equals c? etc.).

But if you only need to compare two roles you could say:

HEAD /rolemgmt/identicalness/{role1}/{role2}

Response:
200: the roles are equal
404: the roles are not equal (i.e. identicalness not found :)
--
LEVEL 14, 23 CUSTOMS STREET, PO BOX 106 769, AUCKLAND 1143, NEW ZEALAND
NZ +64 9 366 0348 | AUS +61 2 80111815 *AOTAL.COM <http://aotal.com/>*

[Johan Groenen]

I think you want to get a comparison between two known roles:

GET /comparison?role_ids=[x,y]

Cheers

Op woensdag 27 mei 2015 20:08:42 UTC+2 schreef Erimei:

[Johan Groenen]

Actually, maybe you want to create a new comparison here:

POST /comparisons 
<< { "role_ids": [x, y] }
>> { "comparison": { "id": z, "role_ids": [x, y], ... } }

Op donderdag 28 mei 2015 18:39:14 UTC+2 schreef Johan Groenen:

[Erimei]

I would like to return user a JSON with differences between roles which he wants compare.

[Thomas Lörcher]

Hi Ermiei,

alternatively you could create a comparison resource like Johan suggested but rather than providing ids of the in the POST request I'd

suggest (as its more restfully) to provide the resource-identifier itself (URL). 

By this there needs not to be taken effort to lookup the URL from an id.

[Michael Thelin]

An alternative solution could be to leverage ETags. Since there's a concept of equality between different role entities, you could return a weak ETag when returning a role. The ETag's value would be calculated based on whatever determines equality, so two roles that'd be considered equal would have the same ETag. I suggest it should be weak since the response for two different roles would still be different. 

Example: Let's say that two roles are considered equal if the have the same access level.

1. Retrieve role1. 

Request:

GET /role/1

Response:

200 OK

ETag: W/"abc"

{

  "id" : 1, 

  "name" : "Arthur",

  "accessLevel" : 5

}

2. Check if role1 and role2 are equal.

Request:

GET /role/2

If-None-Match: W/"abc"

Response:

304 Not Modified

ETag: W/"abc"

(Ok, they're equal since the response was 304 Not Modified.)

3. Check if role2 and role3 are equal (and transitively role1 and role3).

Request:

GET /role/3

If-None-Match: W/"abc"

Response:

200 OK

ETag: W/"def"

{

  "id" : 3, 

  "name" : "Ford",

  "accessLevel" : 10

}

(Ok, role1 and role2 are not equal to role3 since the response was 200 OK.)

Requests could be done using HEAD instead to avoid retrieving the body. 

Of course, this solution would however not allow you to do comparisons between several roles in a single request but it would save you from creating multiple new endpoints while allowing your service to save some bandwidth by using ETags.

Best,

Michael