Alternative to complex REST resource specification

[Les Hartzman]

Hi,

I have a problem I'm working on to develop a REST API to access a resource that has multiple 'levels' to it and am looking for suggestions to best handle it.

As a contrived example, the resources are specified using other qualifiers:

               /myresource/state/{state}/region/{region}/customer/{customer}

In this scenario the customer is not a unique value. That is for a different region or state, the {customer} value could be re-used. This is not something that can be changed, and in actuality the 3 specifiers come from a 3rd party. So to get the correct customer you need the 3 pieces of information.

Should the 2 higher level specifiers be changed to query parameters to simplify the endpoint and still provide some insight into the call? Or another suggestion was to take the 3 values and Base64 encode them and use that as the final ID to the resource so it would become /myresource/customer/{base64-encoded-value}?

Thanks.

Les

[Kijana Woodard]

What problems is is causing?

Why is it complex?

"That is for a different region or state, the {customer} value could be re-used."

What do you mean?

That the following return the same representation?

/purple/square/puzzle-1

/toys/wood/puzzle-1

/puzzles/puzzle-1

--
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 https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Les Hartzman]

There is no "problem" per se. When I refer to 'complex' I'm referring to the accessing the resource by requiring additional pieces of information.

Modifying your example:

     /toys/bin1/material/wood/puzzle/1

    /toys/bin2/material/metal/puzzle/1

These return 2 different resources.

[Kijana Woodard]

By "reused" you're referring to the string "puzzle/1"?

[Jørn Wildt]

If customer isn't unique without the N other parameters I would go for this:

   /customers/{state}/{region}/{customer}

I do not see a need for the intermediate ../state, ../region and ../customer elements in the path.

If you are representing a query for customers then I would use query variables and perhaps make all three optional:

   all customers: /customers

   customers in state x: /customers?state=x

   customers x in any state or region: /customers?customer=x

   customers in region x: /customers?region=x

/Jørn

[Kijana Woodard]

If it is about "puzzle/1", the resource identifiers are not divisible into component parts. Even query string parameters define "a different resource". That "similar strings" have any relation to each other is merely a common convention.

 I read a blog post [1] about the idea of using opaque identifiers [guids] to force clients to use the links returned in previous representations. That kind of drives home the point. There's nothing technical that would stop working [outside of some chosen http framework].

[1] http://blog.ploeh.dk/2013/05/01/rest-lesson-learned-avoid-hackable-urls/

[Neil Brewster]

If state and region are collections, and the relationship really is containment (every customer belongs to one region; every region belongs to one state), then you could go with a slight variation:

               /api/states/{state}/regions/{region}/customers/{customer}

Keeping the intermediate elements lets you act on the collections themselves - e.g. "GET /api/states" to retrieve the list of states.

neil.

[Kijana Woodard]

There's no reason you couldn't have:

"/customers/{state}/{region}/{customer}"

*and*

 

"/api/states"