[RFC] RESTful API

classic Classic list List threaded Threaded
67 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

[RFC] RESTful API

Fabio Mancinelli-4
Dear all,

I worked a bit on the design of the RESTful API and as a result I've
integrated what was written on the
http://dev.xwiki.org/xwiki/bin/view/Design/RestfulAPI page.

There is still a big and important part missing (maybe the most
important one), i.e., the one about the data formats for representations
(in particular the XML schemas to be used in requests and responses). I
am working on it.

Anyway you can already comment on what is present on the page.

Thank you.

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

vmassol
Administrator
Hi Fabio,

Looks good. 2 questions:

1)

# /spaces/{space}/pages/{page}/translations[?start=offset&number=n]  
(The list of all available translations of the page {space}.{page})
# /spaces/{space}/pages/{page}/{version} (The page {space}.{page}. at  
version {version})
# /spaces/{space}/pages/{page}/{lang} (The page {space}.{page} in its  
{lang} translation)
# /spaces/{space}/pages/{page}/{lang}/history (The list of all the  
available revision of the page {space}.{page} in it {lang} translation.)
# /spaces/{space}/pages/{page}/{lang}/{version}

This seems somewhat inconsistent with "pages", "attachments", "objects"

Why not have "versions" and "translations"? For example:
/spaces/{space}/pages/{page}/versions/{version}

Note that I don't know what are the REST best practices. I'm jut  
noticing the inconsistency.

2) How will we support nested spaces?

Thanks
-Vincent

On Dec 15, 2008, at 4:43 PM, Fabio Mancinelli wrote:

> Dear all,
>
> I worked a bit on the design of the RESTful API and as a result I've
> integrated what was written on the
> http://dev.xwiki.org/xwiki/bin/view/Design/RestfulAPI page.
>
> There is still a big and important part missing (maybe the most
> important one), i.e., the one about the data formats for  
> representations
> (in particular the XML schemas to be used in requests and  
> responses). I
> am working on it.
>
> Anyway you can already comment on what is present on the page.
>
> Thank you.
>
> -Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
Vincent Massol wrote:

> Hi Fabio,
>
> Looks good. 2 questions:
>
> 1)
>
> # /spaces/{space}/pages/{page}/translations[?start=offset&number=n]  
> (The list of all available translations of the page {space}.{page})
> # /spaces/{space}/pages/{page}/{version} (The page {space}.{page}. at  
> version {version})
> # /spaces/{space}/pages/{page}/{lang} (The page {space}.{page} in its  
> {lang} translation)
> # /spaces/{space}/pages/{page}/{lang}/history (The list of all the  
> available revision of the page {space}.{page} in it {lang} translation.)
> # /spaces/{space}/pages/{page}/{lang}/{version}
>
> This seems somewhat inconsistent with "pages", "attachments", "objects"
>
> Why not have "versions" and "translations"? For example:
> /spaces/{space}/pages/{page}/versions/{version}
>
I thought that having shorter URIs would be better. But I am not against
 having something like

/spaces/{space}/pages/{page}
/spaces/{space}/pages/{page}/versions
/spaces/{space}/pages/{page}/versions/{version}
/spaces/{space}/pages/{page}/translations
/spaces/{space}/pages/{page}/translations/{language}
/spaces/{space}/pages/{page}/translations/{language}/versions
/spaces/{space}/pages/{page}/translations/{language}/versions/{version}

Or similar.

> Note that I don't know what are the REST best practices. I'm jut  
> noticing the inconsistency.
>
URI design is not that important (as long as the hypermedia constraints
is fully leveraged). However having descriptive URIs and consistent URIs
can enhance the possibility of discovering resources by guessing (i.e.
the level of "serendipity")

> 2) How will we support nested spaces?
>

Actually I didn't address the nested spaces issue.
Spaces can be nested at an arbitrary level?

Thanks.

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

vmassol
Administrator

On Dec 15, 2008, at 5:24 PM, Fabio Mancinelli wrote:

> Vincent Massol wrote:
>> Hi Fabio,
>>
>> Looks good. 2 questions:
>>
>> 1)
>>
>> # /spaces/{space}/pages/{page}/translations[?start=offset&number=n]
>> (The list of all available translations of the page {space}.{page})
>> # /spaces/{space}/pages/{page}/{version} (The page {space}.{page}. at
>> version {version})
>> # /spaces/{space}/pages/{page}/{lang} (The page {space}.{page} in its
>> {lang} translation)
>> # /spaces/{space}/pages/{page}/{lang}/history (The list of all the
>> available revision of the page {space}.{page} in it {lang}  
>> translation.)
>> # /spaces/{space}/pages/{page}/{lang}/{version}
>>
>> This seems somewhat inconsistent with "pages", "attachments",  
>> "objects"
>>
>> Why not have "versions" and "translations"? For example:
>> /spaces/{space}/pages/{page}/versions/{version}
>>
> I thought that having shorter URIs would be better. But I am not  
> against
> having something like
>
> /spaces/{space}/pages/{page}
> /spaces/{space}/pages/{page}/versions
> /spaces/{space}/pages/{page}/versions/{version}
> /spaces/{space}/pages/{page}/translations
> /spaces/{space}/pages/{page}/translations/{language}
> /spaces/{space}/pages/{page}/translations/{language}/versions
> /spaces/{space}/pages/{page}/translations/{language}/versions/
> {version}
>
> Or similar.
>
>> Note that I don't know what are the REST best practices. I'm jut
>> noticing the inconsistency.
>>
> URI design is not that important (as long as the hypermedia  
> constraints
> is fully leveraged). However having descriptive URIs and consistent  
> URIs
> can enhance the possibility of discovering resources by guessing (i.e.
> the level of "serendipity")
>
>> 2) How will we support nested spaces?
>>
>
> Actually I didn't address the nested spaces issue.
> Spaces can be nested at an arbitrary level?

Not yet but we want to support this in the future yes so better design  
a REST API that will work with nested spaces (arbitrary level yes).

Thanks
-Vincent
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by vmassol
Vincent Massol wrote:


>
> Note that I don't know what are the REST best practices. I'm jut  
> noticing the inconsistency.
>

Ok. I saw what you meant.
I modified a bit the resources to remove the inconsistency.
I did this because attachments have also their own versioning.
So you can access a specific version of an attachment either by
requesting an attachment at a given page version
or by requesting an specific version of an attachment.

To be consistent I only left the resources for referring to an
attachment starting for a given page version:

/space/{space}/pages/{page}/attachments
/space/{space}/pages/{page}/attachments/{attachment}
/space/{space}/pages/{page}/{version}/attachments/
/space/{space}/pages/{page}/{version}/attachments/{attachment}

I still maintained the non-verbose version but that can be changed if
there is not an agreement on it.


However it might be still useful to expose attachment resources by using
their own versioning:

/space/{space}/pages/{page}/attachments/{attachment}/history
/space/{space}/pages/{page}/attachments/{attachment}/{version}

Thanks.

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

vmassol
Administrator
Other question:

Why use the plural when retrieving a single instance.

For example:
/spaces --> All spaces
/space/{space} --> One space

Ah just saw you changed that but not everywhere.
Like classes/{class} should be class/{class}
And pages/{page} should be page/{page}
no?

Re nested spaces the best is probably to define a delimiter other than  
"/"

Something like:
/space/this::is::nested/page/WebHome

Of course this would mean that "::" is not allowed in space names.
BTW this would also means that "/" is not allowed in space names.

-Vincent

On Dec 15, 2008, at 5:39 PM, Fabio Mancinelli wrote:

> Vincent Massol wrote:
>
>
>>
>> Note that I don't know what are the REST best practices. I'm jut
>> noticing the inconsistency.
>>
>
> Ok. I saw what you meant.
> I modified a bit the resources to remove the inconsistency.
> I did this because attachments have also their own versioning.
> So you can access a specific version of an attachment either by
> requesting an attachment at a given page version
> or by requesting an specific version of an attachment.
>
> To be consistent I only left the resources for referring to an
> attachment starting for a given page version:
>
> /space/{space}/pages/{page}/attachments
> /space/{space}/pages/{page}/attachments/{attachment}
> /space/{space}/pages/{page}/{version}/attachments/
> /space/{space}/pages/{page}/{version}/attachments/{attachment}
>
> I still maintained the non-verbose version but that can be changed if
> there is not an agreement on it.
>
>
> However it might be still useful to expose attachment resources by  
> using
> their own versioning:
>
> /space/{space}/pages/{page}/attachments/{attachment}/history
> /space/{space}/pages/{page}/attachments/{attachment}/{version}
>
> Thanks.
>
> -Fabio
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Artem Melentyev-3
In reply to this post by Fabio Mancinelli-4
Hi, Fabio.

1) Why we need /spaces/ and /pages/ ?
Can't we use just /{space}/{page}/... ?

What does mean /spaces/{space} GET: retrieves a space? What is space?

2) How could I get all translations of a page?
(so i think {page}/translatios is needed)

3) I think we need {page}/versions instead of {page}/history

Fabio Mancinelli wrote:

> Vincent Massol wrote:
>> Hi Fabio,
>>
>> Looks good. 2 questions:
>>
>> 1)
>>
>> # /spaces/{space}/pages/{page}/translations[?start=offset&number=n]  
>> (The list of all available translations of the page {space}.{page})
>> # /spaces/{space}/pages/{page}/{version} (The page {space}.{page}. at  
>> version {version})
>> # /spaces/{space}/pages/{page}/{lang} (The page {space}.{page} in its  
>> {lang} translation)
>> # /spaces/{space}/pages/{page}/{lang}/history (The list of all the  
>> available revision of the page {space}.{page} in it {lang} translation.)
>> # /spaces/{space}/pages/{page}/{lang}/{version}
>>
>> This seems somewhat inconsistent with "pages", "attachments", "objects"
>>
>> Why not have "versions" and "translations"? For example:
>> /spaces/{space}/pages/{page}/versions/{version}
>>
> I thought that having shorter URIs would be better. But I am not against
>  having something like
>
> /spaces/{space}/pages/{page}
> /spaces/{space}/pages/{page}/versions
> /spaces/{space}/pages/{page}/versions/{version}
> /spaces/{space}/pages/{page}/translations
> /spaces/{space}/pages/{page}/translations/{language}
> /spaces/{space}/pages/{page}/translations/{language}/versions
> /spaces/{space}/pages/{page}/translations/{language}/versions/{version}
>
> Or similar.
>
>> Note that I don't know what are the REST best practices. I'm jut  
>> noticing the inconsistency.
>>
> URI design is not that important (as long as the hypermedia constraints
> is fully leveraged). However having descriptive URIs and consistent URIs
> can enhance the possibility of discovering resources by guessing (i.e.
> the level of "serendipity")
>
>> 2) How will we support nested spaces?
>>
>
> Actually I didn't address the nested spaces issue.
> Spaces can be nested at an arbitrary level?
>
> Thanks.
>
> -Fabio
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
Artem Melentyev wrote:
> Hi, Fabio.
>
> 1) Why we need /spaces/ and /pages/ ?
> Can't we use just /{space}/{page}/... ?
>
Yes, but this might lead to ambiguities in URI routing.

Consider /tags/foo

Is it a a list of pages tagged as foo, or the foo page in the tags space?

By interleaving variable parts with fixed ones this ambiguity can be
solved. This is standard practice however.

Even the plural form. But this can be worked out I guess.

> What does mean /spaces/{space} GET: retrieves a space? What is space?
>
This was a leftover of the current implementation.
Actually we can get rid of this resource.

I am not sure what Alexandru's implementation returned but I guess it
was the {space}.WebHome page.

> 2) How could I get all translations of a page?
> (so i think {page}/translatios is needed)
>
Propbably you missed it. It's already there.


> 3) I think we need {page}/versions instead of {page}/history
>
Again a leftover of the current implementation.
Anyway I agree.


Thanks

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by vmassol
Vincent Massol wrote:

> Other question:
>
> Why use the plural when retrieving a single instance.
>
> For example:
> /spaces --> All spaces
> /space/{space} --> One space
>
> Ah just saw you changed that but not everywhere.
> Like classes/{class} should be class/{class}
> And pages/{page} should be page/{page}
> no?
>
Actually this was a leftover of my Ruby On Rails experience... But yes,
I think that this can be worked out without any problem :)

> Re nested spaces the best is probably to define a delimiter other than  
> "/"
>
> Something like:
> /space/this::is::nested/page/WebHome
>
> Of course this would mean that "::" is not allowed in space names.
> BTW this would also means that "/" is not allowed in space names.
>
This is an interesting solution.
In fact, I don't know if Restlet supports some kind of regular
expression extension on URI templates.

I mean, I am not sure if we can define a "/{space}+/pages/{page}" URI
template as a route for catching nested spaces... To be investigated.

Thanks

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by vmassol
Vincent Massol wrote:

> Other question:
>
> Why use the plural when retrieving a single instance.
>
> For example:
> /spaces --> All spaces
> /space/{space} --> One space
>
> Ah just saw you changed that but not everywhere.
> Like classes/{class} should be class/{class}
> And pages/{page} should be page/{page}
> no?
Actually I think that the plural form makes sense.

/spaces/Main means that in the "list of spaces, I want the Main space",
being /spaces the resource representing that list.

Same thing for classes.

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by vmassol
Vincent Massol wrote:

> Other question:
>
> Why use the plural when retrieving a single instance.
>
> For example:
> /spaces --> All spaces
> /space/{space} --> One space
>
> Ah just saw you changed that but not everywhere.
>
Actually that was a typo.
From my point of view the first component should be "spaces" everywhere :)

I corrected it for the sake of uniformity.

-Fabio
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Sergiu Dumitriu-2
In reply to this post by vmassol
Vincent Massol wrote:

> Hi Fabio,
>
> Looks good. 2 questions:
>
> 1)
>
> # /spaces/{space}/pages/{page}/translations[?start=offset&number=n]  
> (The list of all available translations of the page {space}.{page})
> # /spaces/{space}/pages/{page}/{version} (The page {space}.{page}. at  
> version {version})
> # /spaces/{space}/pages/{page}/{lang} (The page {space}.{page} in its  
> {lang} translation)
> # /spaces/{space}/pages/{page}/{lang}/history (The list of all the  
> available revision of the page {space}.{page} in it {lang} translation.)
> # /spaces/{space}/pages/{page}/{lang}/{version}
>
> This seems somewhat inconsistent with "pages", "attachments", "objects"
>
> Why not have "versions" and "translations"? For example:
> /spaces/{space}/pages/{page}/versions/{version}

+1. We use an identifier for every sub-fragment of information to
eliminate the URL-parsing magic. The more information -> The less
ambiguities -> The simpler things are. Plus,
/spaces/Main/pages/WebHome/2.3 does not suggest that 2.3 is a version.

More, like with version control systems, in the future I'd like to add
support for version tags, which would be accessible using:

/spaces/{space}/pages/{page}/history/HEAD
/spaces/{space}/pages/{page}/history/some_tag

If we don't use /history/, there will be more if-else programming and
more reserved keywords.

> Note that I don't know what are the REST best practices. I'm jut  
> noticing the inconsistency.
>
> 2) How will we support nested spaces?

That's one of the reasons why I insisted on
/spaces/{space}/pages/{page}/ instead of /{space}/{page}/ . Here {space}
can be a nested space, for example:

/spaces/A/Nested/Space/pages/Page/

Drawback: a space hierarchy cannot have a part named 'pages' (or other
special names).

Alternative: Use %2F as the internal separator, like:

/spaces/A%2FNested%2FSpace/pages/Page/

Possible problem: %2F causes Tomcat (with the default settings) to abort
the request, since there are some security problems with poorly designed
applications.

Another problem: This will be incompatible with the current URLs, since
%2F is used to escape / inside space or page names. This URL works quite
well: http://localhost:8080/xwiki/bin/view/Blog%2F2.0/Here%2Fwe%2Fgo ,
where the space is Blog/2.0 and the document is Here/we/go

So, I'd like to stay with:
  /spaces/A/Nested/Space with %2F in it/pages/Page with %2F in it/

> Thanks
> -Vincent
>
> On Dec 15, 2008, at 4:43 PM, Fabio Mancinelli wrote:
>
>> Dear all,
>>
>> I worked a bit on the design of the RESTful API and as a result I've
>> integrated what was written on the
>> http://dev.xwiki.org/xwiki/bin/view/Design/RestfulAPI page.
>>
>> There is still a big and important part missing (maybe the most
>> important one), i.e., the one about the data formats for  
>> representations
>> (in particular the XML schemas to be used in requests and  
>> responses). I
>> am working on it.
>>
>> Anyway you can already comment on what is present on the page.

How about some of the views done in WebDAV, like attachments view and
tree view?

/attachments/spaces/{space}/pages/{page}/{attachment.ext}


I'm not sure about the extension-controlled format. What if the document
contains dots in its name, like "Help/How to create a .pdf"? More
URL-parsing magic? And then what about "How to open a .tar".gz versus
"How to open a .tar.gz"? I think that HTTP Accept header alone is better.


To make XMLs more friendly, we could use XSLT stylesheets to transform
them into HTML on the client.


/space/{space}/pages/{page}/objects/{id} -> what is the id? How to
handle both new GUIDs and old indexes?

I prefer to also have the detailed property view.
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Sergiu Dumitriu-2
In reply to this post by Fabio Mancinelli-4
Fabio Mancinelli wrote:

> Vincent Massol wrote:
>
>
>> Note that I don't know what are the REST best practices. I'm jut  
>> noticing the inconsistency.
>>
>
> Ok. I saw what you meant.
> I modified a bit the resources to remove the inconsistency.
> I did this because attachments have also their own versioning.
> So you can access a specific version of an attachment either by
> requesting an attachment at a given page version
> or by requesting an specific version of an attachment.
>
> To be consistent I only left the resources for referring to an
> attachment starting for a given page version:
>
> /space/{space}/pages/{page}/attachments
> /space/{space}/pages/{page}/attachments/{attachment}
> /space/{space}/pages/{page}/{version}/attachments/
> /space/{space}/pages/{page}/{version}/attachments/{attachment}
>
> I still maintained the non-verbose version but that can be changed if
> there is not an agreement on it.
>
>
> However it might be still useful to expose attachment resources by using
> their own versioning:
>
> /space/{space}/pages/{page}/attachments/{attachment}/history
> /space/{space}/pages/{page}/attachments/{attachment}/{version}

+1 for both (verbose):


/space/{space}/pages/{page}/history/{version}/attachments/{attachment}
/space/{space}/pages/{page}/attachments/{attachment}/history/{version}

But this should not work:

/space/{space}/pages/{page}/history/{version}/attachments/{attachment}/history/{version}

Since we either want to see all the versions of the attachment, or the
attachment variant used in a certain version of the document.
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Sergiu Dumitriu-2
In reply to this post by vmassol
Vincent Massol wrote:

> Other question:
>
> Why use the plural when retrieving a single instance.
>
> For example:
> /spaces --> All spaces
> /space/{space} --> One space
>
> Ah just saw you changed that but not everywhere.
> Like classes/{class} should be class/{class}
> And pages/{page} should be page/{page}
> no?
>
> Re nested spaces the best is probably to define a delimiter other than  
> "/"
>
> Something like:
> /space/this::is::nested/page/WebHome
>
> Of course this would mean that "::" is not allowed in space names.
> BTW this would also means that "/" is not allowed in space names.

It is currently, so dropping it would be a regression. %2F can be used
to escape / inside the space/page name.

--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Sergiu Dumitriu-2
In reply to this post by Artem Melentyev-3
Artem Melentyev wrote:
> 2) How could I get all translations of a page?
> (so i think {page}/translatios is needed)

+1

> 3) I think we need {page}/versions instead of {page}/history

I'm not sure... 'history' is semantically more correct than 'versions',
IMO, at least for me. Versions is closer to variants than to history
(see http://wordnetweb.princeton.edu/perl/webwn?s=version ). It might
even lead the user to think of translations.
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Sergiu Dumitriu-2
In reply to this post by Fabio Mancinelli-4
Fabio Mancinelli wrote:
> Vincent Massol wrote:
>> Note that I don't know what are the REST best practices. I'm jut  
>> noticing the inconsistency.
>>
> URI design is not that important (as long as the hypermedia constraints
> is fully leveraged). However having descriptive URIs and consistent URIs
> can enhance the possibility of discovering resources by guessing (i.e.
> the level of "serendipity")

I disagree. URI design is crucial, although some don't give much
importance to it. I'd rather we sacrifice shortness for meaning. Given
that URLs are already long, there's no need to reduce just a few parts
to save 8 bytes. There's always purl, tinyrl and other services for this.
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

vmassol
Administrator

On Dec 15, 2008, at 6:51 PM, Sergiu Dumitriu wrote:

> Fabio Mancinelli wrote:
>> Vincent Massol wrote:
>>> Note that I don't know what are the REST best practices. I'm jut
>>> noticing the inconsistency.
>>>
>> URI design is not that important (as long as the hypermedia  
>> constraints
>> is fully leveraged). However having descriptive URIs and consistent  
>> URIs
>> can enhance the possibility of discovering resources by guessing  
>> (i.e.
>> the level of "serendipity")
>
> I disagree. URI design is crucial, although some don't give much
> importance to it. I'd rather we sacrifice shortness for meaning. Given
> that URLs are already long, there's no need to reduce just a few parts
> to save 8 bytes. There's always purl, tinyrl and other services for  
> this.

+1 to that.

-Vincent

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Artem Melentyev-3
In reply to this post by Fabio Mancinelli-4
Fabio Mancinelli wrote:

> Artem Melentyev wrote:
>> Hi, Fabio.
>>
>> 1) Why we need /spaces/ and /pages/ ?
>> Can't we use just /{space}/{page}/... ?
>>
> Yes, but this might lead to ambiguities in URI routing.
>
> Consider /tags/foo
>
> Is it a a list of pages tagged as foo, or the foo page in the tags space?
>
> By interleaving variable parts with fixed ones this ambiguity can be
> solved. This is standard practice however.
>
> Even the plural form. But this can be worked out I guess.

Ok. +1 for /space/{space}/page/{page}/...

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by Fabio Mancinelli-4
Dear all,

while I was in the metro I thought of another way of organizing
resources in a more compact way.

I've added a second proposal on the
http://dev.xwiki.org/xwiki/bin/view/Design/RestfulAPI page.

ThomasM also told me that we should take into account the "XWiki"
resource in a mult-wiki environment. This can be done by adding an
optional segment "/wiki/{wiki}/" as a suffix to all the resources.

Thanks.

-Fabio



_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [RFC] RESTful API

Fabio Mancinelli-4
In reply to this post by Fabio Mancinelli-4
Dear all,

I've integrated the remarks done by Sergiu about verbose URIs, object
properties and attachment versions.

Just a comment about the .format. I agree with the fact that there are
some degenerate cases like "How to open a .pdf" and some ambiguous cases
as well like "How to open a .tar.gz"

The idea here is to have a way for specifying a format even without
having control about the Accept header (i.e., with a simple browser).

For handling degenerate cases a simple test can be made on the page
name. And the format should be a simple string with no dots so .tar.gz
should actually be expressed as .tgz

Frankly I find very useful to have a way of typing the URI of a page in
a browser, stick a .pdf suffix and have Acrobat opened on the PDF rendering.

Alternatively, a ?format=XYZ query string can be used instead of the
.format convention. The .format thing, actually, is a "Railism" (e.g.,
see http://weblog.rubyonrails.org/2006/12/19/using-custom-mime-types).

Of course we can decide whether Accept headers have higher priority or not.

-Fabio

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
1234