Hi,
XWiki exposes multiple “services” such as document actions (bin), WebJars, Temporary Resource (and resource handlers in general), REST and soon WebSocket. Some common needs for these services are:
- access XWiki components
- access XWiki documents
XWiki components are registered in namespaces, so in order to use the right XWiki component we need to know the namespace. XWiki documents are grouped in wikis, so in order to load and query the right documents we need to know the wiki.
The relation between the namespace and the wiki concept is that a wiki is a namespace, but a namespace can be something else also.
When using the services I mentioned above we need to pass this information somewhere in the URL so that the service loads the right XWiki components and the right XWiki documents. Most of these services include the wiki in the URL path but recently we have started to use the namespace query string parameter fort the Live Data REST resources.
I’m currently working on integrating the WebSocket API in XWiki and I need to propose an URL scheme, but for this I need to decide:
- what to pass in the URL? wiki vs. namespace
- namespace is more generic but if the namespace is not a wiki then we need to also pass the wiki in order to properly access the XWiki documents
- namespace shifts the focus of the API towards components, while wiki shifts the focus towards documents
- using wiki limits in theory the scope were we look for components, but in practice we use mostly the wiki namespace, so it’s not a big loss
- how to pass it? path vs. query string
- path is harder to change afterwards, and in the case of domain-based sub-wikis it is also redundant
- query parameter is more flexible (we can easily “rename” the parameter later by adding a new one and deprecating the old one) but it is lost when resolving relative URLs (this is one of the reasons we moved the WebJar resource path from the query string to the URL path)
- what name to use for the parameter? I’d go for “wiki” or “namespace”, depending on what we decide for the previous items.
I think it would be good to agree on a best practice in this regard.
WDYT?
Marius