On Jan 19, 2009, at 6:24 PM, John O'Conner wrote:
> HI all,
>
> 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.
> 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.