Mike Pearce's REST feedback

[geoffrey hendrey]

Hi -

Mike has done a lot of development with Ruby on Rails and its REST features. He's the closest I know to a bonafid guru. He sent me this feedback on our REST API. I've inlined my answers below in red. Thanks again for the great feedback!

-geoff

On Nov 15, 2009, at 10:49 PM, Michael Pearce <michael...@yahoo.com> wrote:

I like it.  This looks really good!

I'm not sure i have much of a specifically useful comment on constraints, as my brain wasn't coming up with usages while i was reading it... but hopefully the rest will be constructive:

- Minor note, have done some rails where REST is king and convention is supreme, they would definitely say the URLs should be like this:
http://nextdb.net/nextdb/rest/home/{account}/dbs/{database}/tbls/{table}/
(Notice the pluralization of the urls)
This then makes the "index" URL have a meaning - specifically list all tables or databases for the account.  Users can very easily navigate the URL structure to gain more meaning of the data.
  List all databases: http://nextdb.net/nextdb/rest/home/{account}/dbs
  List all tables in {database}: http://nextdb.net/nextdb/rest/home/{account}/dbs/{database}/tbls
(Most RESTful Railers would also probably use full names in URLs - "tables" and "databases", but whateva...)

That's a really good point. I will probably switch the plural form for both the reasons you mentioned above.

- Path parameters really sound like query strings.  Your point of "order does not matter" sounds like you are even saying it!  Specifically, i can imagine a case where you want data returned from an HTML <form> - using query parameters allows standard browser form submission instead of needing JavaScript to manually create a URL based on form values.  Definitely quite handy.  Why did you end up choosing to add those into the path?

I view path parameters to *tables* as being different from query parameters. I'm sort of thinking in terms of "sets", and thinking that constraining a single column of a table to a particular value or range is more a way to access a "set" than a way to pass parameters to a particular query. For SEO, squid caching, and the like, it didn't seem like query parameters were the right metaphor for allowing an app to make reference to the data set referenced by a table or a column-constrained table expression.

I've actually just (tonight) finished baking the support for accessing named queries via REST, and for those, I *do* use typical "?"-style query parameters. When I put the new query support online tomorrow, you'll see a syntax like .../account/db/q/MYQUERY?p1=x&p2=y

However, even for RESTful access to actual queries, I think we come across the "SEO" problem. For example, if I want to create a page that has links to January's blog posts, and I want to do it via a query, the query parameters will prevent the link from being traversed and indexed by a search engine. Instead of seeing (1) below i'd like to *optionally* be abe to it as (2)

1) .../geoff/blog/q/monthlyQuery?mo=January?yr=2009
2) .../geoff/blog/q/monthlyQuery/mo/January/yr/2009

I think that by supporting both styles we'd get the best of both worlds: i.e. support for url encoded query parameters submitted by browser forms (ala style 1) *and* SEO-goodness that accompanies static links (ala style 2).

- I am surprised i didn't see changing of extensions returning different content types:
  Return JSON: http://nextdb.net/nextdb/rest/home/{account}/dbs/{database}/tbls/{table}.json
  Return XML: http://nextdb.net/nextdb/rest/home/{account}/dbs/{database}/tbls/{table}.xml
  Return default (XML?): http://nextdb.net/nextdb/rest/home/{account}/dbs/{database}/tbls/{table}

Good point. I've got this pipe dream that folks will just use the built-in support for XSLT to generate these types themselves, but I'll be the first to admit that's a pipe dream. I've actually got most of the JSON and XML formatters already written, I just need to plug them in.

-mgp

--
http://nextdb.net - RESTful Relational Database
http://www.nextdb.net/wiki/en/REST

[jon noreika]

Hey Geoff-

I really like the ease of use that the nextdb REST solution provides
for getting data out of my tables.  However, I was wondering if you
had any plans to allow for returning the data from REST calls as JSON
(I see it mentioned below).  Both of the HTML table and XSLT solutions provide great convenience for developers who will ultimately be presenting their data in a browser of some sort; but if I want to make REST calls and just use the data in a non-browser/non-html situation I have to parse out my data.

--

You received this message because you are subscribed to the Google Groups "NextDB Users" group.
To post to this group, send email to nextd...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/nextdb-user?hl=.