Shorter URL for a query or event

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, and one which does not 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. It is implemented by a ruleset installed in the Root Pico of an engine. To use this feature, you must first install the ruleset io.picolabs.rewrite into the root pico. Then you must register each short form with the root pico.

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 best practice. 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" tab. The type of this channel might be "web shortcut", and the name might 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.

Capture the newly created ECI, and register it with the root pico, so that it can be used when it re-writes the short URL to produce the standard URL which the engine actually uses internally. You can use the "Testing" tab of the root pico to do the registration, or use some mechanism provided by the pico engine owner/operator.

Having created the channel as specified, and registered it with the root pico, 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", and registering this first path component (FPC) and the ECI with the root pico, as before, except that the type would be "event" rather than "query".

Note that the FPC "/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 appears in neither 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 the FPC. The io.picolabs.rewrite ruleset in the root pico will detect a collision and not allow you to register a shortcut with an FPC that is already in use.

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, because these other owners will not have access to your root pico's "Testing" tab. This could be a simple single-page application (SPA) or a (shortened!) URL to the root pico for the rewrite:new_rewrite event expecting parameters named "fpc", "eci", and "type". This would allow registering the same event as above using a shortened URL like this.

http://localhost:8080/register-rewrite/rewrite/new_rewrite?fpc=/clear-temps&eci=F6M33KHKhQWNJXpSu9cAM4&type=event

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), and then registering it with the root pico, 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 itself 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.


Copyright Picolabs | Licensed under Creative Commons.