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/