Needs consistent URLs

URLs are our first and primary means of communication. Every action that occurs in Retromod happens by calling a URL. Therefore, the URL structure needs to be both unambiguous and efficient. We are limited in that some browsers restrict URL length to 255 characters, so the URL structure cannot be allowed to include data that is irrelevant, or that could be handled in other ways (e.g. POST data).

It should be noted that some people manually change URLs when the URL structure is consistent rather than attempting to find parts of the system that are self-explanatory (In UI speak, this argument would go that one click and a type is faster than 3 clicks along with their associated page-loads, particularly for experiences users, which are our main user base). For example, users of facebook.com are encouraged to change the URL to facebook.com/username when attempting to create or change their shortcut URL.

It could be said that the URL is the modern-day equivalent of the command line. As such, it needs to be taken seriously and be both straightforward and clear.

==== URL Structure Versioning (Mandatory) ====

Our first requirement is to be able to distinguish between versions of the URL format. If we should ever need to change the URL structure, we will need to be able to detect (and possibly retrofit) forms of the URL to the current structure.

The simplest way to do this would be to make the first section before the first slash to be the version number:
e.g. /1.0/rest/of/url/

If we required version numbers to be numbers (or, at least, the initial character to be a number), then we could shortcut the URL versioning such that:
/rest/of/url
would redirect to:
/1.0/rest/of/url

==== Returning type (Mandatory) ====

We need to be able to specify whether the requesting application is requesting output in a web format, javascript, XML, etc. This is important for interactive clients.

==== Security and Access ====

The URL-handling code needs to be linked to the both the security/access code, and the "returning type". If, for example, a user attempts to access an object to which they have not been provided access, the URL-handling code needs to determine the return type and send an appropriate signal in that return type.

==== Instantiation vs Component ====

We probably need to differentiate between a Component and an instantiation of a Component. Currently we use the terms "component" to mean the component itself, and "module" to mean the component instantiated with parameters. Each of these need to be able to be called directly. However, calling a component without parameters needs to be clever and determine if the caller meant to call a instantiated module, perhaps by offering instantiated modules the user has rights to (done by returning a message in the specified return type).

A simple way to do this would be to make part of the URL structure specify the type of object they're trying to access. e.g.
/1.0/c/[componentname]
/1.0/m/[modulename]

This would consume at least 2 characters, and provide us with the ability to differentiate between components and modules of the same name.

Another way to solve this could be to make all parts of the system "objects" and then have a lookup table based on the name. This table could then specify the component or module that should be called. This would work similarly to the module table in RM2 and, in fact, could be included in the same table simply by adding the components without parameters as modules, or by adding an extra field to the table specifying the type of call to be made.

The down side to this, of course, would be that naming would be restricted, and we may end up with administrators calling modules "component1".

It's also possible that another way to solve this would be to cut out direct access to components. However, we may end up with the same problem happening with widgets.

==== Widgetonents (Need a better name for these) ====

The atomic unit of Retromod has been getting smaller with every version release. RM2 saw the introduction of Javascript to the mix which was a real hack. Javascript clients, along with other interactive forms of the API, need to consider calling smaller sections of code that do simple things. For example, rather than having the entire Scheduling Table return everything in that screen all at once when 90% of it won't even be seen, it would make more sense to return URL references to the information so that the client can call that section of code if the user requests it.

This concept is slightly different from Widgets in the same way that Components are different from Modules. Widgets require parameters. Some of those parameters will need to come from the UI as part of a POST request, while others may come from the calling component or module.