[kforge-dev] url naming (bug and suggestion)

[John Bywater]

Hi Rufus,

Rufus Pollock wrote:

> Small Bug
> =========
>
> At present it seems that
>   /project/<project-name>/service
> has been changed to
>   /project/<project-name>/services
>
> but that not all links in templates have been updated.


They have now :-)

http://project.knowledgeforge.net/kforge/trac/changeset/961

But I only found one place that wasn't right (the list of links to 
services on a project page).

Was this the error you found?

>
> Suggestion for url naming guidelines
> ====================================
>
> However this brings me to a general question about our url naming 
> guidelines. I'd like to propose the following conventions:
>
> 1. All urls should be lower case with underscoress e.g. access_denied 
> rather than accessDenied etc
> 2. Singular rather than the plural (just as we do for db tables). e.g.
>   service rather than services,
>   project rather than projects,
>   user rather than users etc
>
> what do people think?


To describe what happened, I should say that following 'Choose One Name 
And Use It Everywhere', the urls have started to follow the domain model 
object attribute names, which I would hope everbody would agree should 
use a singular name for a singular attribute such as where a member has 
a role, and a plural name for a plural attribute such as where a project 
has many services.

At the domain model level, it appears that naming a list of services as 
'service' would be worse than calling it 'services'. I don't think there 
is any question about this.

Then, considering the adjacent layers:

Firstly, the database layer has no notion of a plural attribute, as this 
has been lost within the object model<=>relational table mapping. Within 
the relational table entities, there are only tables of records, with 
foriegn keys to link everything together. All instances of a type of 
entity are stored together as records in a table, and the table is named 
after the entity type. A database entity type corresponds to a domain 
model class, and is normally singular, but could easily be plural, such 
as in the case where the entity is a fixed length array.

So it isn't quite correct to say that the table names are singular. 
Rather, the table names follow domain model class names, which in KForge 
(and in general) are singular. (As we know, SQLObject makes table names 
by converting the domain model class names into lower case names with 
underscores.)

Secondly, the presentation layer has no notion of domain classes, but 
works against the domain model registry. The domain model registry works 
with the registers of domain objects, which are collections and 
therefore named with plural names. For example in KForge, this achieves 
the distinction between the services of different projects, which are 
all the same type of entity ("Service") and appear in the same database 
table (the "service" table), but which appear as separate collections of 
one project or another, where the collection is named "services" on the 
project.

I don't think it makes too much sense to argue that because the table is 
named after the class, that a particular collection should also.

To my mind, it seems more reasonable, and it appears more efficient 
overall, to use the model attribute names in the presentation layer, 
even if this does mean we have a few 's' characters that could be 
abbreviated out. But we don't like abbreviations, do we?

(In CKAN, the url is parsed and used to find attributes on domain 
objects: if we wanted to rename domain model attributes in the 
presentation layer, we would need to think of a reliable two-way 
renaming scheme, or put some look-up mapping into the views to ranems, 
or something like that.)

Also, I am perfectly happy to use lower case with underscores in urls, 
rather than camel case.

>
> Login/logout url
> ================
>
> We used to have /user/login and /user/logout but I think this has been 
> changed to /login and /logout. I have to say I preferred the original. 
> This isn't a biggie but whatever we do we need to make sure the code 
> is consistent (e.g. src/kforge/handlers/modpython.py is currently 
> using the old style (/user/login) which means the redirect does not work


Wooops... I fixed this up just now (to be consistent; to use /login/).

>
> Again what do people think?


I thought it was simpler to complete the decoupling of user 
authentication from the user model. I don't mind if we put /login/ after 
/user but it seems to make slightly less sense. Internally, the 
authentication views do not depend on the person views.

http://project.knowledgeforge.net/kforge/trac/browser/trunk/src/kforge/django/apps/kui/views/kui.py
http://project.knowledgeforge.net/kforge/trac/browser/trunk/src/kforge/django/apps/kui/views/person.py

However, authentication information (password, username) exists within 
the Person class, but we have talked about separating these attributes 
out (L. v. Beethoven doesn't need to login..).

Best wishes,

John.


>
> Regards,
>
> Rufus
>