Some inspiration from: Mike Schinkel's 'Well Designed URLs are Beautiful essay.
In counterpoint, it's probably also a good idea to read this cautionary tale.
Many URLs in Confluence are ugly. Page URLs are less ugly, most of the time, but could still do with some improvement.
Ideas
Basic
- Replace /display with /spaces to reflect its function better
- Move user profiles (and personal spaces/blogs) into /users
- Maintain redirects for existing /display/* URLs, obviously
- Detect when an application server supports UTF-8 encoded URLs (and provide documentation for application servers for configuring URL encoding), and disable our ugly hackarounds when they're not needed.
Advanced: Postfixed
Move to a /realm/entity/view URL scheme. For example:
- /spaces/STUFF/My+Page+Title/view/html (/spaces/STUFF/My+Page+Title will be an alias to this, as would /spaces/STUFF/My+Page+Title/view)
- /spaces/STUFF/My+Page+Title/view/pdf
- /spaces/STUFF/My+Page+Title/view/worddoc
- /spaces/STUFF/My+Page+Title/view/source
- /spaces/STUFF/My+Page+Title/edit
- /spaces/STUFF/My+Page+Title/info
- /spaces/STUFF/My+Page+Title/history
Views will be pluggable, of course. Themes will be able to ask the ViewManager for a list of all available views for this object type so themes can display links to them.
Advanced: Prefixed
The alternative is to move to a /action/realm/entity scheme. For example:
- /view/STUFF/My+Page+Title
- /view/STUFF/My+Page+Title.html (alias to the above)
- /view/STUFF/My+Page+Title.pdf (PDF view of the page)
- /view/STUFF/My+Page+Title.doc (Word document)
- /view/STUFF/My+Page+Title.txt (source code)
- /edit/STUFF/My+Page+Title
- /info/STUFF/My+Page+Title
- /history/STUFF/My+Page+Title
As above, views would be pluggable, based on their extension (*.pdf, etc). A possible issue here is that it is quite legal to have two pages named 'My Page Title' and 'My Page Title.pdf', so what happens then when trying to access the PDF view of the first page?
Questions
- How would this mess with other plans for namespacing pages? Say you have a page called edit namespaced under a page called My+Page+Title? Should we make all actions start with an underscore, i.e. My+Page+Title/_edit? That'd be more ugly, but it might be safest.
- What happens if there is a space with a key that's conflicting with a URL keyword - eg. a space with key "spaces"?
- There must be lots of people who use "up" buttons (see discussion below) - how do we get intuitive results when clicking the "up" button?
- Can we create a URL format that intuitively transposes in to wiki link notation? eg. it's a pain linking to news items, comments and mail messages at present
31 Comments
Hide/Show CommentsMar 01, 2006
David Peterson [CustomWare]
I'm not sure what special characters are now allowed in page names, but you could do something like one of the following:
Alternately, you could do this:
etc.
Mar 01, 2006
Charles Miller
Aesthetically, /foo fits in better to me with the way URLs work. And if we're going to be going for weird characters anyway, bar/_foo seems easier to read than bar!foo or bar:foo.
Mar 01, 2006
David Peterson [CustomWare]
Here's a comparison for reference:
Mode
Prefixed
Postfixed
View HTML
/view/FOO/Bar
/spaces/FOO/Bar
View PDF
/view/FOO/Bar.pdf
/spaces/FOO/Bar/_view/pdf
Edit
/edit/FOO/Bar
/spaces/FOO/Bar/_edit
Info
/info/FOO/Bar
/spaces/FOO/Bar/_info
Page Attachments
/attachments/FOO/Bar
/spaces/FOO/Bar/_attachments
Space attachments
/attachments/FOO
/spaces/FOO/_attachments
Browse Space pages
/browse/FOO/pages
/spaces/FOO/_pages
Browse Space tempates
/browse/FOO/templates
/spaces/FOO/_templates
Mar 01, 2006
Guy Fraser (Adaptavist)
Another thing to take in to account is various browsers or browser plugins allow navigation to parent directories - eg. the google toolbar has an "up" button which simply vapes whatever is after the last / in a URL as on most websites that will take you to the parent folder.
I believe that in this scenario, the post-fixed URL's would work better.
Mar 01, 2006
Matt Ryall (Atlassian)
I think I agree with David's second suggestion.
If you put the action name first, you don't need anything to distinguish it. It also reads nicer (confluence, edit, my page) and won't clash with any namespacing or nesting of pages, spaces, etc.
Then maybe actions just get their extra detail right as an extra path component:
The view handler gets any URL that starts with /view/, which then refers the request onto a html view handler or pdf view handler based on the remaining bit of the path. Doing this would potentially clash with nested spaces, though.
Mar 01, 2006
Guy Fraser (Adaptavist)
What happens when you hit the "up" button and eventually get to:
/view/html --> What gets viewed as html?
/view --> What gets viewed?
To quote from the article linked at the top of this page...
Mar 01, 2006
Guy Fraser (Adaptavist)
Addendum:
With the postfixed URL's, if using : as a separator, then something like this:
/spaces/foo/bar/view:pdf (view page "bar" in space "foo" as a pdf)
would be converted to the following when the "up" button is pressed:
/spaces/foo/bar
Which would be default html view.
Still ugly, I know, and would conflict with page namespaces. However, it's the sort of thing that needs ponderance otherwise fans of the "up" button see logical things happening when they use it (personally I never use it, but there must be lots of people that do for it to be on google toolbar, and various browser plugins and also "accessible" browsers)
Mar 01, 2006
David Peterson [CustomWare]
I'm not sure that that's what I'd expect or want when pressing 'up' anyway... I think that is pretty undefined territory, really - it's really a different view of the same resource (html, pdf, edit, whatever) and I wouldn't necessarily expect to 'switch views' by pressing 'up' - I'd expect to move further up the hierarchy.
Mar 01, 2006
Guy Fraser (Adaptavist)
Yes, good point.
The issue still remains, what happens when they get to this:
/view/html
or this:
/view
Perhaps the "mode" could be within a space, eg:
/space/FOO/view:html/page
So "up" would give:
/space/FOO/view:html = space home page as html (or pdf or whatever)
/space/FOO = urg, same thing?
/space = list of spaces?
/ = dashboard?
I guess there is one other factor to take in to consideration - what happens if people have a space with a key that's now a URL keyword, eg. we've got a space called Dashboard which could conflict with any future /dashboard link to the real dashboard, etc? Ok, bad example, what if someone has a space with key "view"?
Mar 01, 2006
Guy Fraser (Adaptavist)
Do we need the "view" bit?
Eg: /space/foo/bar:pdf = view page "bar" as a pdf
Mar 01, 2006
David Peterson [CustomWare]
Yes. Because, as you mentioned, what if someone names their space 'edit' or 'info' (that would be a fairly common space key, I would think).
Mar 01, 2006
Guy Fraser (Adaptavist)
You could have:
/space/foo/bar:edit
/space/foo/bar:info
/space/foo/bar:pdf
/space/foo/bar:word
/space/foo/bar:source
/space/foo/bar:attachments
/space/foo/bar:history
Mar 01, 2006
Guy Fraser (Adaptavist)
and likewise...
/feed/title:rss
/feed/title:rss2
/feed/title:atom
/labels/fish:pdf
etc?
Mar 01, 2006
David Peterson [CustomWare]
What happens when you go to '/display' currently? 404, that's what... So it isn't hackable at the moment anyway. But yes, I get your point. Let's see:
URL
Display
/view
/dashboard.action
/edit
/dashboard.action (except that any links you click will edit the resource by default)
/view/SPACE
/view/SPACE/Home (or whatever the home page for the space is)
/view/pdf
/dashboard.action (except that any links will view the resource as a PDF
That said, for the last case (/view/pdf) if 'pdf was the file post-fix (/view/SPACE/Page.pdf), that wouldn't even be an issue, since you only get the PDF view if you specify it attached to a page. However, the disadvantage is that it may conflict with existing pages (eg a page who's name is actually 'Page.pdf'). Not sure what the best rule is there.
Mar 01, 2006
Charles Miller
The 404 on /display is a bug. We were going to make it redirect to the dashboard, which goes to show how semantically empty the word 'display' is in this context.
The accepted 'model' of URLs is one of containment. /foo/bar means that 'bar' is contained within 'foo'. So does a page contain its attachments, or is there a bucket of attachments that contains another bucket named after the page? I'd say the former is a more satisfying model.
Mar 01, 2006
David Peterson [CustomWare]
I agree, essentially, and I'm not sure that the 'edit' or 'info' actions are logically contained by the 'view' action for a page.
I've been wrestling with the same problem in WebDAV - the thing is that Confluence doesn't fit neatly into a 'containment' model...
In the WebDAV context, this is how it's currently working (I love tables
):
/webdav/SPACE/
A directory listing other directories representing root pages
/webdav/SPACE/Page
A directory containing the following:
/webdav/SPACE/Page/Sub+Page
A directory listing the same info as for 'Page', but for the Sub Page
There are a couple of problems here with regards to confluence.
Mar 01, 2006
Guy Fraser (Adaptavist)
Also, what if there is a sub-page with the same name as an attachment, etc. Yes, it's a tricky one!
I guess a new version of Confluence would be able to restrict such things (although would that in itself cause problems?) but there would then be issues with upgrading from earlier versions of Confluence.
*brain melts*
Mar 01, 2006
Guy Fraser (Adaptavist)
I love the idea of page.pdf and page.doc - that is perfect!!!
Mar 01, 2006
Guy Fraser (Adaptavist)
Ok, it's 3:30am over here and I just re-read your comment and understood it this time. However, having a .pdf or .doc extension to a page would be extremely intuative. You could have .txt for the page source
Mar 01, 2006
Guy Fraser (Adaptavist)
.html for the html view
Mar 01, 2006
Matt Ryall (Atlassian)
You can't take everything in that article as automatically applying to Confluence.
For example his first point, 'Well Designed URLs Point to Content that Does Not Change', obviously doesn't apply.
Confluence needs its URLs to describe actions as well as objects, so the concepts that apply to static websites need to be adapted.
Mar 01, 2006
Guy Fraser (Adaptavist)
David,
How would this affect your Linking Plugin? Would it chimp or merely require a new Utilities plugin?
Guy
Mar 01, 2006
David Peterson [CustomWare]
Assuming the old action URLs still work, it won't affect it at all. But yeah, it would be mostly a matter of providing a new Utilitities Plugin. Of course, if once 'bundled jars' are implemented, this will have to change regardless...
Mar 01, 2006
Guy Fraser (Adaptavist)
I'm not overly keen on the display -> spaces idea. We often use descriptive space keys, for example:
www.mysite.com/display/website/page+title
With the proposed change, that would become:
www.mysite.com/spaces/website/page+title
Which to an end-user would make little sense unless they understand the concept of spaces.
Love the /users idea
Not sure about news. If news articles became user specific blogs, that would certainly make more sense.
Right now, we are moving towards using pages with a label of "news" to deliver news, however it would be nice if there was a date based way to view all content, eg:
/date/2006/03/01/ = view everything that happened on that date
/space/date/... = view everything that happened on that date in the specific space
/users/date/... = view all user specific stuff for the given date
It would be nice if we could store RSS feeds built with the feed builder and access them like this:
/rss = list all stored feeds
/rss/feed+title = a specific feed
Would this be better for source view:
.../my+page+title/view/source
Basically treat the source view as if it were simply another way of looking at the page?
It would be nice to have searches with a pretty url:
.../search/query
Mar 01, 2006
Matt Ryall (Atlassian)
I think I disagree with the postfixing of an extension for page exports.
1. URLs do not represent files.
2. The postfixing of a file-type extension is peculiar to certain operating systems. It therefore might not be intuitive to many people.
3. The values 'html', 'pdf', etc. represent a parameter ('type') to the action 'view', and I think this is a more general problem (providing parameters to actions) that warrants a more general solution.
URLs have a standard already for providing parameters:
action/entity?arg=value. It's ugly, but it's there to allow multiple parameters and for parameters that aren't used so frequently (such as exporting pages).As another issue, perhaps we should look at improving links to things that are currently hidden away in Confluence menus:
I'm sure there's many more.
This would need some kind of generic URL->action handler. Perhaps actions could register their own 'guessable' URLs dynamically.
Mar 01, 2006
David Peterson [CustomWare]
You are correct that URLs don't necessarily represent files, however they I would submit that most often do represent files and that, although file extensions are not required by all operating systems, they are supported and understood by all operating systems. And I would also suggest that everyone is used to seeing them in web sites.
I also don't believe that in the case of 'View' that there are any other parameters which would apply to an entity. Then again, I guess there are comments, etc which would have to be handled somehow. Hmm... However, the following doesn't make any sense to me:
All that said, I'm not sold on any one of the suggestions for the New URL standard so far - they all have advantages and disadvantages.
Mar 02, 2006
Sulka Haro
I understand some people need / want to have a prefix on the URLs for each page but here's a million dollar question: does basic viewing even need the prefixes?
If I have a space called STUFF and page called Foo, why can't the url just be
www.mysite.com/STUFF/Foo
You would need to prevent a couple space keys so actions are not overwritten but this would probably work in 99% of the cases.
Mar 02, 2006
David Peterson [CustomWare]
The main problem with this is that hundreds, if not thousands, of spaces already exist out there, many of which quite likely conflict with the other 'subdirectories' which already exist (eg 'admin' and 'display' I see as being quite likely to exist as Space keys). What do we do when someone upgrades to our new-and-improved /SPACEKEY/Page version and we discover they have a space called 'admin' already. Not good.
May 22, 2006
Matt Ryall (Atlassian)
We'd be only changing URLs as part of a significant overhaul in a major new version. As such, it would be possible to add new reserved words, as long as we provided an upgrade task to work around issues such as these.
Since almost all bookmarks would be broken by the URL changes anyway, forcing the user to change one space key would not be such a big deal.
Jun 15, 2006
Brian Mckellar
From past expierence with many other (inhouse) information servers, the goal should be to optimize for the thousands of readers, where 99% of them do not even know how Confluence work. Typically our inhouse servers work such that if we know the server name, and a (hot) keyword, it can be used to access the root page for the information. Typical example would be http://portal/topic. It is intuitive and the way how people quick stab into the dark as a first try to get to what they want.
In addition, this is our way of communication. In a meeting one would say "for more information, see the central wiki on topic". Here "topic" are typically well-know abbreviations for large projects which are well-known through the complete company. This is an easy way for everyone to work (and the way we do work!).
Already just the word "display" in the URL is insider magic to only those few that work and publish on Confluence, our thousands of readers to do know this word. Same for "go", "view", etc.
Thus, my basic tenor would be that http://confluence/space should be one URL that always work, even if you have to hardcode this as special case!
Confluence can consider to make one reserved name that they use for all internal related URLs. Typically adding special characters and a mangled URL (guid as ugly form) should be sufficient to exclude a clash with exiting space key. Or more industrial strength, use the availability of action keywords on the URL to decide what was required. For example "?action=view" (default), "?action=edit" or "?action=info", etc.
regards, brian
May 30, 2010
Matt Miller
I recently had a need to abstract Confluence's URL scheme and came across a clever way to do so by feeding Apache's mod_rewrite with data from a SQL view of the confluence database.
Blogged/Documented here in the hopes others will also find my method useful