15 Dec
2008
15 Dec
'08
6:27 p.m.
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/