On Jan 19, 2009, at 12:39 PM, Paul Sandoz wrote:
>>
>> I have been searching the web for best practice information for
>> defining URIs for my situation, but I can't quite find the
>> information I need. Maybe someone here can help?
>>
>> I've used Jersey to define the following endpoints:
>>
>> GET /accounts -- retrieves a list of account summary objects
>> (List<AccountSummary>), which are shorter versions of a full
>> account objects
>> GET /accounts/<#> -- retrieves a single account object (Account)
>>
>> POST /accounts -- create a new account
>>
>> My question is whether I'm violating some best-practice by using
>> the same /accounts endpoint to retrieve both summary objects and
>> account objects. The list of account summary objects is obviously
>> smaller than a list of full accounts, and the GET /accounts/<#>
>> allows the user to get all the details of a specific account...yet
>> something feels like I'm violating a naming principle.
>>
>
> IMHO you are not violating a best-practice. I think it is quite
> common for lists of stuff to contain a summary of information rather
> than everything. That summary is often just enough for the client to
> do something useful with a list e.g. present in a table while not
> being unduly large to make it harder for clients to process, or to
> take too much time to transmit.
>
+1. One thing I'd add is for each item in the summary list to contain
an explicit link to the individual account. That way the client
doesn't have to know much about how you structure your URIs after
retrieving the initial summary.
Marc.
>
>> Do you see anything incorrect about my naming conventions for
>> retrieving a list of account summaries and a specific account? One
>> obvious effect of this URI design is that we have no obvious way to
>> retrieve more than one Account (List<Account>). What do you think?
>>
>
> I would design the service by use-case. If you need to get a summary
> list and a complete list you could implement such support with a
> query parameter associated with /accounts, perhaps with a way to get
> a range or list of accounts. Alternatively you could support them by
> different URIs:
>
> /accounts -- summary list
> /accounts/full -- full list
>
> The latter can be linked to in the former. The nice thing about this
> approach is which ever way you start with you can introduce an
> alternative without breaking existing clients.
>
> Paul.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>
---
Marc Hadley <marc.hadley at sun.com>
CTO Office, Sun Microsystems.