Help on design composite API Resources

[Diego Magalhães]

Hello guys,

   I'm currently designing a content gallery API and need some advices on how to implement it with java+jersey, the operations are easy but the combinations made my head explodes :)

/medias/{id} -> returns a single media

/medias/{string-alias} -> lookup on a table for a id

/medias/categories/{id} -> list of <media> inside category x

/medias/categories/{string-alias} -> list of <media> inside category x, which is looked up by string-alias

/medias/genres/{id} -> ....

/medias/genres/{string-alias} -> ....

and a few other composite uses of other resources to mimic a content gallery, but I can combine it like /categories/{string-alias}/genre/{string-alias} and all sort of stuff.

Is there a way or examples point on how to do it?

I'm kinda lost and before trying to reinvent the wheel, I'm looking for examples on how to do it.

Diego Magalhães
http://diegomagalhaes.com
claro @ +55 21 9411 2823

[Steve Klabnik]

URIs are opaque identifiers, it literally does not matter. Do what
makes the most sense to you.

There aren't enough details for me to tell you what I'd do.

[Diego Magalhães]

I'd like to first see what has been done and then evaluate on my work. I rather not design something like get Request URI, split on pairs and try do call every child Resource.

Diego Magalhães
http://diegomagalhaes.com
claro @ +55 21 9411 2823

--
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.

[Mike Schinkel]

Opaque to clients, but not required to be opaque from perspective of the API server.

It's a heck of a lot easier to architect and to understand APIs when the URIs can be comprehended than if, for example, every API was a guid.

-Mike

[Steve Klabnik]

> It's a heck of a lot easier to architect and to understand APIs when the URIs can be comprehended than if, for example, every API was a guid.

I'm not saying there's no value to having URIs be done a certain way.
But from an architectural perspective, it doesn't matter.

They're for people.

[Mike Schinkel]

On Sep 26, 2012, at 4:21 PM, Steve Klabnik <st...@steveklabnik.com> wrote:

I'm not saying there's no value to having URIs be done a certain way.
But from an architectural perspective, it doesn't matter.

They're for people.

So then saying "it literally does not matter" isn't really correct, right? It does matter, to people.

I only belabor this point because I've seen people read the URI opacity constraint to mean that their URLs MUST be unintelligible. You know that's not the case but often people reading things like what you wrote do not, hence why I added the caveat. It's also helpful to have people model URLs; it helps then validate an API's architecture because the URL modeling process enables them to recognize when the architecture is a mismatch for the purpose of the API.

-Mike

[Diego Magalhães]

Couldn't agree more. The API is that, already design to the point that doesn't matter what the user choses beside the first item

he'll get the list representation of the first path and the subsequent will be translate in a series of constraints to the query, but I don't wan't it to be a querystring, hence the questioning. 

Is there a way to do it in jersey beside getting the URI and splitting?

Diego Magalhães
http://diegomagalhaes.com
claro @ +55 21 9411 2823

[Greg Brail]

It sounds like you're looking for specific Jersey programming help. Don't know where the best place is to find that, but in general I know that it's not difficult to declare resources such as "/medias/{id}" and have Jersey invoke your method with whatever goes there. From there, though, it's up to you, because Jersey isn't going to know whether a particular path means "id" or "string-alias".

In general, though, I like the idea of giving each resource a unique ID, and also a developer-friendly alias. But then you have to be able to write code that can quickly distinguish between an ID and an alias. If you can do that -- using a regular expression for instance -- then give it a try.

I do like the idea of having sub-collections called "genres," "categories," etc, because then a developer can write:

GET /genres -- return a list of genres

GET /genres/classical -- return IDs of media in the classical genre

but the problem comes if you want to be able to search in multiple ways, though -- how do you do that? So the alternative is to use query parameters:

GET /medias?genre=classical&language=en&createdBefore=1800&sort=name&limit=10

I think that a combination of the two would likely be most usable by developers.

and if it gets more complicated than that then you should look at OData...

--
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.
 
 

--
Gregory Brail  |  Technology  |  Apigee

[Diego Magalhães]

Thanks Greg,

We've opted to break the paths in pairs and use that on criterias, the querystrings will be used as infrastructural changes like pagination, limits, etc. 

Diego Magalhães
http://diegomagalhaes.com
claro @ +55 21 9411 2823