This is a proposition and discussion for the URL structure for MoinMoin 2. Consider it a work in progress and just one possibility.
General assumptions
All the examles assume that the wiki is hosted at http://example.com and it's script name is /wiki, so the base address is http://example.com/wiki. Anything enclosed in square or angle brackets in the URL is meta-description, since they are forbidden inside URLs. So, for example, http://example.com/wiki/[page name] means that [page name] part will be substituted with the actual page name.
Technical limitations
All characters that are not allowed inside URLs must be %-encoded. Since there is a large discrepancy of how %-encoded URLs characters are treated by web server and browser software, disabling the special behavior of some characters like slashes by %-encoding them is not advised. Different deployment methods will give deployed web application different results: raw URL, decoded URL without any way of determining which part was encoded, or (in case of Apache) a 404 error when the URL contains %-encoded slashes!
Due to differences in configuration of web servers and specifics of frameworks, it's also inadvisable to distinguish between URLs that end with a slash and ones that don't. Always assume that the slash may be added/removed by the user, browser, proxy, web server, middleware or framework. Same goes for doubled slashes -- always treat them as just slash.
Compatibility notes
Obviously, changing application's URL patterns is going to result in invalidating all the externally saved links. Fortunately, the most linked resource, the view action, is not going to change. MoinMoin has warnings about not using the other URLs in external links, so if you did it's your fault.
MoinMoin also has a markup for constructing URLs. There is especially one place where this mechanism has to be used -- a download link to an attachment. This markup will have to generate a different URL now, breaking the general URL-constructing mechanism.
Page (Item) addresses -- View action
The most fundamental action that is used almost all the time on the wiki is the "view" action, which renders the contents of the page as HTML, together with the theme's navigation elements, and provides links and buttons for all the other actions. This can be easily 99% of all URLs called for a wiki site, so it's the most important. We want it to be simple, so it will only consist of the url-encoded item title, like this: http://example.com/wiki/[%-encoded item title]. You can also have subitems, so it may look like this: http://example.com/wiki/[item title]/[subitem title]. You can have any level of nesting, as long as you don't exceed the maximum allowed title length (the URL itself has limits too). Some examples:
http://exmaple.com/wiki/SomePage
http://exmaple.com/wiki/SomePage/
http://exmaple.com/wiki/some%20page
http://exmaple.com/wiki/some%20page/subpage
http://exmaple.com/wiki/some%20page%2fsubpage
Since the item title may contain pretty much any characters and can have any level of nesting, the above definition would exhaust pretty much all possible URLs. That's why we need an exception. If the item title starts with one of the special characters (currently "+", "@", "~", but more may be reserved), it has to be doubled:
http://exmaple.com/wiki/++%20sign
http://exmaple.com/wiki/%2b%2b%20sign
http://exmaple.com/wiki/@@home
http://exmaple.com/wiki/++%20sign/++subpage
There are also two other sane ways of treating this special case, they may prove better than the above:
Use a single escape character, for example "\": http://exmaple.com/wiki/\+%20sign, http://exmaple.com/wiki/\\escape
Use explicit action name: http://exmaple.com/wiki/+view/+%20sign
Other actions
Anything that starts with un-escaped special character is treated specially. In particular, if it starts with the "+" character, it's an alternate view of the page or the wiki. Some examples:
http://exmaple.com/wiki/+edit/PageName -- editor view
http://exmaple.com/wiki/+download/image.png -- raw view
http://exmaple.com/wiki/+search -- search form for the wiki
Putting the action name at the beginning of the URL instead of the end has some important consequences:
It's very easy to filter with robots.txt file.
- It's easy to password-protect or rewrite with webserver configuration.
- Makes it easy to refer to other resources in the same view, for example, a "+download"-ed .css file may refer to images with just their names, like "image.png", instead of "../image.png/+download" or something like that.
- The links in the pages may be relative, ".." will lead to the parent item, not to the same item but in default view.
Hierarchical actions
Some views are really just a list of resources which can be in turn obtained by adding something to their URL. That's the basic idea of REST that you have a hierarchy of resources. This can be nicely illustrated on the example of page history. You can see the history of a "PageName" page with http://exmaple.com/wiki/+history/PageName -- you get the usual listing of the revisions. Then, when you click on revision 43, you go to, say, http://example.com/wiki/+history/PageName/@43 and see how it looked then. Note that "@" character that distinguishes it from a subpage name. Other action may have even deeper hierarchies.
Parametrized actions
Sometimes an action takes a parameter, but it's not part of the hierarchy. You may want to force a mime type, pass a search query or provide a new item name for rename action. These all belong to the good old query paramters:
* http://example.com/wiki/+search?q=ponies * http://example.com/wiki/+download/style.css?mimetype=text/plain * http://exmpale.com/wiki/+rename/PageName?name=CoolerPageName