From bburke at redhat.com Thu Jul 1 03:59:13 2010 From: bburke at redhat.com (Bill Burke) Date: Wed, 30 Jun 2010 23:59:13 -0400 Subject: [rest-practices] dumping link headers In-Reply-To: <540039002.1570781277888935577.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> References: <540039002.1570781277888935577.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Message-ID: <4C2C1291.8020607@redhat.com> Sergey Beryozkin wrote: > Hi > > As far as the user's experience is concerned, what would be the difference between dealing with related pairs of custom headers > (or complex Link header) and say some custom XMl/JSON response body representing the same information ? > Depends what you're doing. For REST Messaging, I'm using Link headers so I don't have to have an envelope format. They work very nicely there. > Using Name & Name-Type convention is simple and easy on the eye, it looks fine, but this approach is probably less likely to work well with generic clients ? Link might do better > Don't care much about "easy on the eye". I'm positioning REST (maybe incorrectly) as Zero client footprint, meaning, you only need an HTTP client lib. Since most HTTP clients don't support link headers yet, a header parser would be required to be written, maintained, and distributed to clients. Yeah, its only 10-20 lines of code, but it contradicts the user experience I'm trying to push. At least for the RESTful interfaces I'm doing for HornetQ and TX, I don't see how a generic client could take advantage of the Link headers I'm publishing. You could make a case that caches might like Link better, but for the above interfaces I'm doing, its mostly POST/PUT interactions. Finally, IIRC, HTTP 1.1 states that custom headers are assumed to be entity headers anyways. Not sure how that translates for generic clients though. -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bkearney at redhat.com Thu Jul 22 18:42:38 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Thu, 22 Jul 2010 14:42:38 -0400 Subject: [rest-practices] Pagination API Message-ID: <4C48911E.9010608@redhat.com> We are starting to look at adding pagination to our collection. I wanted to know if anyone has a set of query parameters they have already made use of to overlay pagination onto an api. Thanks! -- bk From kwatsen at juniper.net Thu Jul 22 20:08:12 2010 From: kwatsen at juniper.net (Kent Watsen) Date: Thu, 22 Jul 2010 13:08:12 -0700 Subject: [rest-practices] Pagination API In-Reply-To: <4C48911E.9010608@redhat.com> References: <4C48911E.9010608@redhat.com> Message-ID: <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> ABNF Syntax: "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" Notes: * Returns at most "limit" items, starting with the "start" item in the collection * "0" is the default value used when none is specified * Paging is over live data; elements may shift over the course of multiple requests Examples: * paging=(limit=25) * paging=(start=0,limit=25) K. -----Original Message----- From: rest-practices-bounces at redhat.com [mailto:rest-practices-bounces at redhat.com] On Behalf Of Bryan Kearney Sent: Thursday, July 22, 2010 2:43 PM To: rest-practices Subject: [rest-practices] Pagination API We are starting to look at adding pagination to our collection. I wanted to know if anyone has a set of query parameters they have already made use of to overlay pagination onto an api. Thanks! -- bk _______________________________________________ rest-practices mailing list rest-practices at redhat.com https://www.redhat.com/mailman/listinfo/rest-practices From bkearney at redhat.com Thu Jul 22 20:29:03 2010 From: bkearney at redhat.com (Bryan Kearney) Date: Thu, 22 Jul 2010 16:29:03 -0400 Subject: [rest-practices] Pagination API In-Reply-To: <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> Message-ID: <4C48AA0F.7030601@redhat.com> Thanks... did you incorporate sorting in this as well? -- bk On 07/22/2010 04:08 PM, Kent Watsen wrote: > ABNF Syntax: > > "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" > > Notes: > > * Returns at most "limit" items, starting with the "start" item in the collection > * "0" is the default value used when none is specified > * Paging is over live data; elements may shift over the course of multiple requests > > Examples: > > * paging=(limit=25) > * paging=(start=0,limit=25) > > K. > > > -----Original Message----- > From: rest-practices-bounces at redhat.com [mailto:rest-practices-bounces at redhat.com] On Behalf Of Bryan Kearney > Sent: Thursday, July 22, 2010 2:43 PM > To: rest-practices > Subject: [rest-practices] Pagination API > > We are starting to look at adding pagination to our collection. I wanted > to know if anyone has a set of query parameters they have already made > use of to overlay pagination onto an api. > > Thanks! > > -- bk > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From kwatsen at juniper.net Thu Jul 22 20:34:05 2010 From: kwatsen at juniper.net (Kent Watsen) Date: Thu, 22 Jul 2010 13:34:05 -0700 Subject: [rest-practices] Pagination API In-Reply-To: <4C48AA0F.7030601@redhat.com> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> <4C48AA0F.7030601@redhat.com> Message-ID: <84600D05C20FF943918238042D7670FD36D4365B5B@EMBX01-HQ.jnpr.net> ABNF Syntax: = "sortby=(" ")" = ["," ] = *char [ ] = "(" ["ascending" / "descending"] ")" Notes: * The value encodes a path using periods ('.') relative to the object contained by the collection. The path can only reference local scalar values; it cannot reference inner-list or traverse into any referenced object * "ascending" is the default value used when one is not specified Examples: * sortby=(first-name) * sortby=(contact-info.email-addr(descending)) * sortby=(status(descending),last-name(ascending)) K. -----Original Message----- From: Bryan Kearney [mailto:bkearney at redhat.com] Sent: Thursday, July 22, 2010 4:29 PM To: Kent Watsen Cc: rest-practices Subject: Re: [rest-practices] Pagination API Thanks... did you incorporate sorting in this as well? -- bk On 07/22/2010 04:08 PM, Kent Watsen wrote: > ABNF Syntax: > > "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" > > Notes: > > * Returns at most "limit" items, starting with the "start" item in the collection > * "0" is the default value used when none is specified > * Paging is over live data; elements may shift over the course of multiple requests > > Examples: > > * paging=(limit=25) > * paging=(start=0,limit=25) > > K. > > > -----Original Message----- > From: rest-practices-bounces at redhat.com [mailto:rest-practices-bounces at redhat.com] On Behalf Of Bryan Kearney > Sent: Thursday, July 22, 2010 2:43 PM > To: rest-practices > Subject: [rest-practices] Pagination API > > We are starting to look at adding pagination to our collection. I wanted > to know if anyone has a set of query parameters they have already made > use of to overlay pagination onto an api. > > Thanks! > > -- bk > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From lutter at redhat.com Fri Jul 23 19:23:09 2010 From: lutter at redhat.com (David Lutterkort) Date: Fri, 23 Jul 2010 12:23:09 -0700 Subject: [rest-practices] Pagination API In-Reply-To: <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> Message-ID: <1279912989.2273.17.camel@avon.watzmann.net> On Thu, 2010-07-22 at 13:08 -0700, Kent Watsen wrote: > ABNF Syntax: > > "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" > > Notes: > > * Returns at most "limit" items, starting with the "start" item in the collection > * "0" is the default value used when none is specified > * Paging is over live data; elements may shift over the course of multiple requests > > Examples: > > * paging=(limit=25) > * paging=(start=0,limit=25) What's the reason for having a special format within the query parameter ? That forces the client to do extra work if they want to jump to item 42 (rather than just tacking '?start=42&limit=25' at the end of the URL) I would just go with parameters 'page', 'limit', and 'order' (addressing per-page, rather than per-item, seems simpler to me, with counting pages from 1), i.e. something like '/index?page=5&limit=10&order=name,modified_at.desc,color.asc' David From sberyozk at redhat.com Mon Jul 26 10:04:17 2010 From: sberyozk at redhat.com (Sergey Beryozkin) Date: Mon, 26 Jul 2010 06:04:17 -0400 (EDT) Subject: [rest-practices] Pagination API In-Reply-To: <1279912989.2273.17.camel@avon.watzmann.net> Message-ID: <70241047.1465331280138657716.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Hi > > > > Examples: > > > > * paging=(limit=25) > > * paging=(start=0,limit=25) > > What's the reason for having a special format within the query > parameter ? That forces the client to do extra work if they want to > jump > to item 42 (rather than just tacking '?start=42&limit=25' at the end > of > the URL) > > I would just go with parameters 'page', 'limit', and 'order' > (addressing > per-page, rather than per-item, seems simpler to me, with counting > pages > from 1), i.e. something like > '/index?page=5&limit=10&order=name,modified_at.desc,color.asc' Grouping the related parameters may be the reason. In your example, it is likely the actual query may end up looking like this on the wire : ?limit=10&order=name&page=5 depending on how the actual client keeps the query options, not a big deal from the prcessing point of view, but a bit confusing IMHO, given that we have 'system' (page, limit) and some application specific (order) queries intermixed. I agree though that introducing a special format makes things a bit more complicated - personally I'd go for something similar to what you suggest but consider making it clear that page & limit are not the usual queries : /index?_page=5&_limit=10&order=name Sergey > > David > > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices From bburke at redhat.com Mon Jul 26 13:58:13 2010 From: bburke at redhat.com (Bill Burke) Date: Mon, 26 Jul 2010 09:58:13 -0400 Subject: [rest-practices] Pagination API In-Reply-To: <1279912989.2273.17.camel@avon.watzmann.net> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> <1279912989.2273.17.camel@avon.watzmann.net> Message-ID: <4C4D9475.1070401@redhat.com> I agree namespace it if you have to. paging.limit paging.start David Lutterkort wrote: > On Thu, 2010-07-22 at 13:08 -0700, Kent Watsen wrote: >> ABNF Syntax: >> >> "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" >> >> Notes: >> >> * Returns at most "limit" items, starting with the "start" item in the collection >> * "0" is the default value used when none is specified >> * Paging is over live data; elements may shift over the course of multiple requests >> >> Examples: >> >> * paging=(limit=25) >> * paging=(start=0,limit=25) > > What's the reason for having a special format within the query > parameter ? That forces the client to do extra work if they want to jump > to item 42 (rather than just tacking '?start=42&limit=25' at the end of > the URL) > > I would just go with parameters 'page', 'limit', and 'order' (addressing > per-page, rather than per-item, seems simpler to me, with counting pages > from 1), i.e. something like > '/index?page=5&limit=10&order=name,modified_at.desc,color.asc' > > David > > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From kwatsen at juniper.net Mon Jul 26 15:30:46 2010 From: kwatsen at juniper.net (Kent Watsen) Date: Mon, 26 Jul 2010 08:30:46 -0700 Subject: [rest-practices] Pagination API In-Reply-To: <4C4D9475.1070401@redhat.com> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> <1279912989.2273.17.camel@avon.watzmann.net> <4C4D9475.1070401@redhat.com> Message-ID: <84600D05C20FF943918238042D7670FD36D45AF32F@EMBX01-HQ.jnpr.net> I agree that the paging api could use simple query parameters, but multi-column sorting (example sent previously), field selections (a la LinkedIn API), and ad hoc filter expressions all require parentheses. Once the infrastructure has been developed to support parentheses, using them for paging seems better K. -----Original Message----- From: Bill Burke [mailto:bburke at redhat.com] Sent: Monday, July 26, 2010 9:58 AM To: David Lutterkort Cc: Kent Watsen; rest-practices Subject: Re: [rest-practices] Pagination API I agree namespace it if you have to. paging.limit paging.start David Lutterkort wrote: > On Thu, 2010-07-22 at 13:08 -0700, Kent Watsen wrote: >> ABNF Syntax: >> >> "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" >> >> Notes: >> >> * Returns at most "limit" items, starting with the "start" item in the collection >> * "0" is the default value used when none is specified >> * Paging is over live data; elements may shift over the course of multiple requests >> >> Examples: >> >> * paging=(limit=25) >> * paging=(start=0,limit=25) > > What's the reason for having a special format within the query > parameter ? That forces the client to do extra work if they want to jump > to item 42 (rather than just tacking '?start=42&limit=25' at the end of > the URL) > > I would just go with parameters 'page', 'limit', and 'order' (addressing > per-page, rather than per-item, seems simpler to me, with counting pages > from 1), i.e. something like > '/index?page=5&limit=10&order=name,modified_at.desc,color.asc' > > David > > > _______________________________________________ > rest-practices mailing list > rest-practices at redhat.com > https://www.redhat.com/mailman/listinfo/rest-practices -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bburke at redhat.com Mon Jul 26 15:41:31 2010 From: bburke at redhat.com (Bill Burke) Date: Mon, 26 Jul 2010 11:41:31 -0400 Subject: [rest-practices] Pagination API In-Reply-To: <84600D05C20FF943918238042D7670FD36D45AF32F@EMBX01-HQ.jnpr.net> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> <1279912989.2273.17.camel@avon.watzmann.net> <4C4D9475.1070401@redhat.com> <84600D05C20FF943918238042D7670FD36D45AF32F@EMBX01-HQ.jnpr.net> Message-ID: <4C4DACAB.4040806@redhat.com> Create a new representation for complex queries maybe? And use POST instead? Downside is you lose HTTP caching + GET. Kent Watsen wrote: > I agree that the paging api could use simple query parameters, but multi-column sorting (example sent previously), field selections (a la LinkedIn API), and ad hoc filter expressions all require parentheses. Once the infrastructure has been developed to support parentheses, using them for paging seems better > > K. > > > -----Original Message----- > From: Bill Burke [mailto:bburke at redhat.com] > Sent: Monday, July 26, 2010 9:58 AM > To: David Lutterkort > Cc: Kent Watsen; rest-practices > Subject: Re: [rest-practices] Pagination API > > I agree namespace it if you have to. > > paging.limit paging.start > > David Lutterkort wrote: >> On Thu, 2010-07-22 at 13:08 -0700, Kent Watsen wrote: >>> ABNF Syntax: >>> >>> "paging=(" ["start=" 1*DIGIT ","] "limit=" 1*DIGIT ")" >>> >>> Notes: >>> >>> * Returns at most "limit" items, starting with the "start" item in the collection >>> * "0" is the default value used when none is specified >>> * Paging is over live data; elements may shift over the course of multiple requests >>> >>> Examples: >>> >>> * paging=(limit=25) >>> * paging=(start=0,limit=25) >> What's the reason for having a special format within the query >> parameter ? That forces the client to do extra work if they want to jump >> to item 42 (rather than just tacking '?start=42&limit=25' at the end of >> the URL) >> >> I would just go with parameters 'page', 'limit', and 'order' (addressing >> per-page, rather than per-item, seems simpler to me, with counting pages >> from 1), i.e. something like >> '/index?page=5&limit=10&order=name,modified_at.desc,color.asc' >> >> David >> >> >> _______________________________________________ >> rest-practices mailing list >> rest-practices at redhat.com >> https://www.redhat.com/mailman/listinfo/rest-practices > -- Bill Burke JBoss, a division of Red Hat http://bill.burkecentral.com From bmcwhirt at redhat.com Mon Jul 26 17:28:13 2010 From: bmcwhirt at redhat.com (Bob McWhirter) Date: Mon, 26 Jul 2010 13:28:13 -0400 Subject: [rest-practices] Pagination API In-Reply-To: <84600D05C20FF943918238042D7670FD36D45AF32F@EMBX01-HQ.jnpr.net> References: <4C48911E.9010608@redhat.com> <84600D05C20FF943918238042D7670FD36D4365B1B@EMBX01-HQ.jnpr.net> <1279912989.2273.17.camel@avon.watzmann.net> <4C4D9475.1070401@redhat.com> <84600D05C20FF943918238042D7670FD36D45AF32F@EMBX01-HQ.jnpr.net> Message-ID: > I agree that the paging api could use simple query parameters, but multi-column sorting (example sent previously), field selections (a la LinkedIn API), and ad hoc filter expressions all require parentheses. Once the infrastructure has been developed to support parentheses, using them for paging seems better The simple case of Bob the Developer hacking URLs, though, to see what he can see, simple pagination is still better. Even if the server can support parens, my fingers don't desire to type them. -Bob