Oftentimes you will have a URL to access one of your picos and you will want to use that URL frequently and/or share it with others. In such cases you might prefer a shorter URL, which does not have to include the random-looking event channel identifier (ECI).

Of course, you could use one of the many available URL shorteners, such as bitly or tinyurl. If one of these suits your needs, read no further.

Node pico engine URL shortener

The node pico engine has a built-in feature to shorten query and event URLs. Here is a running example URL

http://localhost:8080/sky/cloud/JdRh1jpgmp5mFeWBLGwmoE/my.room/tempsDay.txt?date=2017-12-14

which happens to obtain all of the temperature data from my room for the given date. We will learn how to shorten this to

http://localhost:8080/my.room/tempsDay.txt?date=2017-12-14

so if this kind of shortening will be useful, read on to see how to specify it.

Create a new channel

This is a discipline that you should have in any case. For each usage of a pico, that pico should have a specific channel. This allows you to revoke that usage without interfering with other usages of the same pico.

To create a channel for this purpose, in the UI go to the "Channels" tag. The type of this channel must be "web shortcut" (without the quotes and a single space between the two words), and the name must match the first part of the path of the short URL. In the running example, this would be "/my.room".

Note that the ECI which had been used in the full /sky/cloud URL is not shown in the list. It was deleted before the screenshot was captured. That is because the specific value need not be known or shared at all for the shorter link to work. The engine will select the channel of type "web shortcut" with the name my.room and use that channel's ECI when it re-writes the short URL to produce the standard URL which the engine actually uses internally.

Having created the channel as specified, the short URL will now work.

Short URL for an event

Supposing that my pico had a ruleset that reacted to the temps:clear event. Then the standard URL would look like this

http://localhost:8080/sky/event/F6M33KHKhQWNJXpSu9cAM4/clear-temps/temps/clear

and could be shortened to

http://localhost:8080/clear-temps/temps/clear

by creating a channel of type "web shortcut" with name "/clear-temps".

Note that "clear-temps" can be chosen arbitrarily, because it is the event identifier (EID). Contrast this with the case for queries in which the name of the channel must match your ruleset identifier (RID). For events, the RID does not appear in either the longer standard URL nor in the short one.

Caveats and hints

This technique is most useful when you own and operate the node pico engine. When you own a pico that lives on an engine operated by someone else, there is a risk of inadvertent naming collisions.

Of course, you really ought to operate your own pico engine. It's not that hard (see Pico Engine Quickstart) and it gives you more personal freedom. If you grant others access to your engine and allow them to have an owner pico (see Account management using the Root Pico), you might wish to set up some kind of registration procedure for naming web shortcuts to avoid duplicates. If there is a collision – if more than two owners choose the same web shortcut name -- the one that happens to have the ECI that sorts earlier in alphabetic order will win.

Like the longer, standard links for events and queries, the shorter links are not permalinks unless you take steps to keep your engine running permanently and never change the ECI. The shorter links would have more tendancy towards permanence because when deleting an ECI you can create a new channel (with proper name and type) without requiring the link itself to change.

Notice that for events, the first part of the path in a shorter link can be chosen somewhat arbitrarily, because it becomes the EID in the (internally) rewritten longer link that actually is seen by the engine. In the case of queries, the first part of the path in the shorter link must exactly match the RID. In both cases, the first part of the path (immediately following the domain name and port (if present)) must match this regular expression: re#/[\/\w.-]*#, i.e. it must begin with a forward slash, followed by letters, digits, or the underscore, period, or hypen characters only.

If you are wondering why the ECI for the secret channel named "admin" is redacted in the image above, it is because this is the only channel that the pico has which is not fungible, which cannot be deleted without requiring the pico itself to also be deleted. So, even though the pico is running on an engine which I control, and which is running on a machine which I control, I'm not taking any chances.

This capability will be introduced into the engine in version, 0.44.0.