Xorion URLs

[Kurt Cagle]

To help get things kicked off, I thought it might be worth laying out a few ideas I have on core architecture.

The examples given here are built with an eye towards eXist usage, but at the same time I'm trying to keep this sufficiently generic that porting to different XML database systems should be relatively simple.

In general, nearly every transaction that takes place makes use of a RESTful interface, broken out in the following way (this assumes URL rewriting capability in the system):

1) http://server.com:port/xorion/collection[/subcollections][//key].presentation[?[q=queryexpr;][s=sortexpr;][p=page;][pg=pagesize;]]

where [ ] indicates optional content.

Thus, if you wanted to access the second page of blogs written by Kurt Cagle as an HTML table, in descending order, which features the category term "xml", then the full expression may look something like:

2) http://server.com:8100/xorion/blogs.blocktable.html?q=author:Kurt+Cagle+term:xml;s=date+descending;p=1

while an individual blog (say the one with title "Xorion Does and Don'ts" might be given as:

3) http://server.com:8100/xorion/blogs//xorion+does+and+donts.page.html

Everything that presents content has a URL - blocks, panels, and pages.

Every page directed to the website is actually sent to one internal URL:

4) http://server.com:8100/rest/xorion/dispatch.xq,

which parses the given URL to determine the underlying collection, key, presentation, query string, sort string, page and page size. I believe that in a restful system these are ultimately just about all of the variables that are needed for determining sufficient state for the application.

Now, given this, one point that can (and should) be asked, is why the URL in #2 doesn't look like:

5) http://server.com:8100/xorion/blogs/Kurt+Cagle/xml/.blocktable.html?s=date+descending;p=1

The reason for the differentiation here is that internally, a collection (such as blogs) is bound to a specific query (usually in XQuery) through what I call a services contract (in a file called services.xml). Collections are essentially just names that may or may not correspond to an actual set of resources, though in most cases it makes a great deal of sense to do so (these resources are usually contained internally in a collection /db/../site/resources/resourceName/data). Thus, if Xorion kept all of the blog entries in the resource folder "blogs" then the collection would be in /db/../site/reources/blogs/data (where the ellision indicates that there may be some unknown set of intermediate database collections between the root and site.

Sub-collections are collections that start with the primary collection name (such as /blogs) but then add qualifiers (/blogs/published). These subcollections use the same resource data as the primary collections, but point to a different pipeline for processing. The query string parameter contained in the q parameter (assuming semi-colon rather than ampersand based delimiters) provides a set of parameters for the query being invoked, and these parameters may change depending upon the given script.

Now, there are two possibilities for interpreting a given URL. One is to use the approach in #5, but that assumes that these are the only constraints acting on the blogs set, and that there are no possibilities for subcollections. If you had a thousand bloggers, this act could be quite expensive. On the other hand, if you go: http://server.com:8100/xorion/blogs.block_table.html?q=author:Kurt+Cagle then the search for the /blogs collection involves a much smaller subset of possibilities in the services.xml document for the appropriate query. Significantly, one subcollection could be /blogs/authors which would then simplify the expected query string parameter:

6) http://server.com:8100/xorion/blogs/authors.blocktable.html?q=Kurt+Cagle

as you wouldn't need to qualify the facet being considered.

The reference here to blocktable.html should be seen as a representation. This is the particular face that is applied to the entries that are filtered, sorted and partitioned, and each face or representation has a terminating pipe or step that actually does the transformation. I'll be laying out the corresponding services document soon, and this may better illustrate how the pipelines are constructed and constrained.

Additionally, remember that these are RESTful services - a given resource collection would in turn have different pipelines depending upon whether you're talking about HTTP PUT, POST, GET or DELETE. Again, this may make more sense once I publish the service document, which shows how these pieces work together.

Comments?

Kurt Cagle
Managing Editor
http://xmlToday.org

[Anthony Ettinger]

Is there an intention to provide a mechanism for mashing up different
REST apis into one application?
I found this to be something that keeps propping up as a requirement,
hitting 3-4 different API providers and constructing one page. I have
done this with XML and XSLT, where I insert the different API
responses into a generic XML ui vocabulary, and then transform that to
xhtml or whatever.

--
Anthony Ettinger
408-656-2473
http://anthony.ettinger.name

[Kurt Cagle]

I'm planning on setting up a generic API that can be used to wrap each XQuery implementation when they support some form of client-side API calls. For instance, eXist has a fairly robust httpclient api:

xmlns:httpclient = "http://exist-db.org/xquery/httpclient"

httpclient:clear-persistent-cookies() empty()

Clears any persistent cookies stored in the current session on the client.

httpclient:delete($url as xs:anyURI, $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP DELETE request. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers><httpclient:body type="xml|xhtml|text|binary" mimetype="returned content mimetype">body content</httpclient:body></httpclient:response> where XML body content will be returned as a Node, HTML body content will be tidied into an XML compatible form, a body with mime-type of "text/..." will be returned as a URLEncoded string, and any other body content will be returned as xs:base64Binary encoded data.

$url	The URL to process
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:get($url as xs:anyURI, $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP GET request. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers><httpclient:body type="xml|xhtml|text|binary" mimetype="returned content mimetype">body content</httpclient:body></httpclient:response> where XML body content will be returned as a Node, HTML body content will be tidied into an XML compatible form, a body with mime-type of "text/..." will be returned as a URLEncoded string, and any other body content will be returned as xs:base64Binary encoded data.

$url	The URL to process
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:head($url as xs:anyURI, $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP HEAD request. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers></httpclient:response>

$url	The URL to process
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:options($url as xs:anyURI, $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP OPTIONS request. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers></httpclient:response>

$url	The URL to process
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:post($url as xs:anyURI, $content as item(), $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP POST request. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers><httpclient:body type="xml|xhtml|text|binary" mimetype="returned content mimetype">body content</httpclient:body></httpclient:response> where XML body content will be returned as a Node, HTML body content will be tidied into an XML compatible form, a body with mime-type of "text/..." will be returned as a URLEncoded string, and any other body content will be returned as xs:base64Binary encoded data.

$url	The URL to process
$content	The XML POST payload/content. If it is an XML Node it will be serialized, any other type will be atomized into a string.
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:post-form($url as xs:anyURI, $content as element(), $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP POST request for a form. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers><httpclient:body type="xml|xhtml|text|binary" mimetype="returned content mimetype">body content</httpclient:body></httpclient:response> where XML body content will be returned as a Node, HTML body content will be tidied into an XML compatible form, a body with mime-type of "text/..." will be returned as a URLEncoded string, and any other body content will be returned as xs:base64Binary encoded data.

$url	The URL to process
$content	The form data in the format <httpclient:fields><httpclient:field name="" value=""/>...</httpclient:fields>. If the field values will be suitably URLEncoded and sent with the mime type application/x-www-form-urlencoded.
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

httpclient:put($url as xs:anyURI, $content as node(), $persist as xs:boolean, $request-headers as element()?) item()

Performs a HTTP PUT request.. This method returns the HTTP response encoded as an XML fragment, that looks as follows: <httpclient:response xmlns:httpclient="http://exist-db.org/xquery/httpclient" statusCode="200"><httpclient:headers><httpclient:header name="name" value="value"/>...</httpclient:headers><httpclient:body type="xml|xhtml|text|binary" mimetype="returned content mimetype">body content</httpclient:body></httpclient:response> where XML body content will be returned as a Node, HTML body content will be tidied into an XML compatible form, a body with mime-type of "text/..." will be returned as a URLEncoded string, and any other body content will be returned as xs:base64Binary encoded data.

$url	The URL to process
$content	The XML PUT payload/content. If it is an XML Node it will be serialized, any other type will be atomized into a string.
$persist	The to indicate if the cookies persist for the query lifetime
$request-headers	Any HTTP Request Headers to set in the form <headers><header name="" value=""/></headers>

Returns the XML body content

which can be used to make both RESTful and RPC calls. It's likely that I'll probably just subclass this module under a different namespace.

Now, internally, I am envisioning REST,  XML-RPC and  SOAP layers that would sit on top of this, with the relevant encoding information stored in specific XML documents that could then be used for invoking specific services. The documents would store the necessary invocation data, while we'd also define soap:, xmlrpc: and rest: modules for invoking these services. I don't have a specific API in mind for them yet, but its likely something we'll need to set up early on.

Suggestions?

Kurt Cagle
Managing Editor
http://xmlToday.org

[dRabeuf]

About syntax interface (URL - Predicates - Semantic - RESTFul and so
on)
I search - I found ()
http://www.w3.org/DesignIssues/Notation3 ()
I read this document some months ago - I am happy because I lost the
reference
Citation [Tim Berners-Lee, Editor
First version date: 1998,
Last change: $Id: Notation3.html,v 1.135 2006/03/09 02:59:33 timbl Exp
$]

N3 RDFa OWL are in some family but can we Transform one of these
syntax to Another ? (XSLT - Rewriting)
According to the drawing: NO - Theoretically saying == Not isomorph

Anyway. That is very important is: these languages are imperative (as
Prolog)
The underlying rule is: be imperative when you can - If you cannot try
again - Then call a function

I prefer N3 but too formal, not easily understandable (too compact)

Some timbl pages are like that
[difficult to find,but they are very clear if we think before for
other things]

I found another design issue http://www.w3.org/DesignIssues/N3QL.html

Anyway XOrion - XML must goes on - We cannot solve all theory issues -
Bur we must be aware

Dominique Rabeuf XRX/NXD Member

On 8 oct, 01:33, Kurt Cagle <kurt.ca...@gmail.com> wrote:
> To help get things kicked off, I thought it might be worth laying out a few
> ideas I have on core architecture.
>
> The examples given here are built with an eye towards eXist usage, but at
> the same time I'm trying to keep this sufficiently generic that porting to
> different XML database systems should be relatively simple.
>
> In general, nearly every transaction that takes place makes use of a RESTful
> interface, broken out in the following way (this assumes URL rewriting
> capability in the system):
>

> 1)http://server.com:port/xorion/collection[/subcollections][//key].presentation[?[q=queryexpr;][s=sortexpr;][p=page;] [pg=pagesize;]]

>
> where [ ] indicates optional content.
>
> Thus, if you wanted to access the second page of blogs written by Kurt Cagle
> as an HTML table, in descending order, which features the category term
> "xml", then the full expression may look something like:
>

> 2)http://server.com:8100/xorion/blogs.blocktable.html?q=author:Kurt+Cag...

>
> while an individual blog (say the one with title "Xorion Does and Don'ts"
> might be given as:
>

> 3)http://server.com:8100/xorion/blogs//xorion+does+and+donts.page.html

>
> Everything that presents content has a URL - blocks, panels, and pages.
>
> Every page directed to the website is actually sent to one internal URL:
>

> 4)http://server.com:8100/rest/xorion/dispatch.xq,

>
> which parses the given URL to determine the underlying collection, key,
> presentation, query string, sort string, page and page size. I believe that
> in a restful system these are ultimately just about all of the variables
> that are needed for determining sufficient state for the application.
>
> Now, given this, one point that can (and should) be asked, is why the URL in
> #2 doesn't look like:
>

> 5)http://server.com:8100/xorion/blogs/Kurt+Cagle/xml/.blocktable.html?s...

>
> The reason for the differentiation here is that internally, a collection
> (such as blogs) is bound to a specific query (usually in XQuery) through
> what I call a services contract (in a file called services.xml). Collections
> are essentially just names that may or may not correspond to an actual set
> of resources, though in most cases it makes a great deal of sense to do so
> (these resources are usually contained internally in a collection

> /db/../site/resources/*resourceName*/data). Thus, if Xorion kept all of the

> blog entries in the resource folder "blogs" then the collection would be in
> /db/../site/reources/blogs/data (where the ellision indicates that there may
> be some unknown set of intermediate database collections between the root
> and site.
>
> Sub-collections are collections that start with the primary collection name
> (such as /blogs) but then add qualifiers (/blogs/published). These
> subcollections use the same resource data as the primary collections, but
> point to a different pipeline for processing. The query string parameter
> contained in the q parameter (assuming semi-colon rather than ampersand
> based delimiters) provides a set of parameters for the query being invoked,
> and these parameters may change depending upon the given script.
>
> Now, there are two possibilities for interpreting a given URL. One is to use
> the approach in #5, but that assumes that these are the only constraints
> acting on the blogs set, and that there are no possibilities for
> subcollections. If you had a thousand bloggers, this act could be quite

> expensive. On the other hand, if you go:http://server.com:8100/xorion/blogs.block_table.html?q=author:Kurt+Ca...
> the search for the
> */blogs* collection involves a much smaller subset of possibilities in the

> services.xml document for the appropriate query. Significantly, one

> subcollection could be */blogs/authors* which would then simplify the
> expected query string parameter:
>
> 6)http://server.com:8100/xorion/blogs/authors.blocktable.html?q=Kurt+Cagle

[Kurt Cagle]

I'm not going to get into N3 discussions - these aren't really relevant to the task at hand. I suspect that we will end up encoding documents in RDF, and at some point I see building an N3 presenter, but that's FAR down the road at this point.

Kurt Cagle
Managing Editor
http://xmlToday.org

[dRabeuf]

I agree because we have to make something even if the theory is not
yet finished
May be theory exploration will never end (In fact, I am sure)
We have enough theory Web basis to build something solid as old
mansions

Navier - Stoke problem is not yet solve and we take plane and
predicate weather, because we need (are) approximations
Nothing is perfect - My (your) house is not perfect but I (you) sleep
in !
That is life
DR

On 8 oct, 22:49, Kurt Cagle <kurt.ca...@gmail.com> wrote:
> I'm not going to get into N3 discussions - these aren't really relevant to
> the task at hand. I suspect that we will end up encoding documents in RDF,
> and at some point I see building an N3 presenter, but that's FAR down the
> road at this point.
>
> Kurt Cagle

> Managing Editorhttp://xmlToday.org

>
>
>
> On Thu, Oct 8, 2009 at 1:11 PM, dRabeuf <drab...@gmail.com> wrote:
>
> > About syntax interface (URL - Predicates - Semantic - RESTFul and so
> > on)
> > I search - I found ()
> >http://www.w3.org/DesignIssues/Notation3()
> > I read this document some months ago - I am happy because I lost the
> > reference
> > Citation [Tim Berners-Lee, Editor
> > First version date: 1998,
> > Last change: $Id: Notation3.html,v 1.135 2006/03/09 02:59:33 timbl Exp
> > $]
>
> > N3 RDFa OWL are in some family but can we Transform one of these
> > syntax to Another ? (XSLT - Rewriting)
> > According to the drawing: NO - Theoretically saying == Not isomorph
>
> > Anyway. That is very important is: these languages are imperative (as
> > Prolog)
> > The underlying rule is: be imperative when you can - If you cannot try
> > again - Then call a function
>
> > I prefer N3 but too formal, not easily understandable (too compact)
>
> > Some timbl pages are like that
> > [difficult to find,but  they are very clear if we think before for
> > other things]
>

> > I found another design issuehttp://www.w3.org/DesignIssues/N3QL.html