Grass Valley iControl V.6.02 - Manual (Page 317)

iControl
User Guide
307
the alarm path, alarm name and so on. We don't embed the path and name in the alarm URI
"just in case".
Physical vs. logical
Very often you have to make the choice between physical and logical concepts. The most
obvious example of this is whether to use host names or IP addresses in URIs. Ideally we want
to support both (see Future directions), but until we do, in general we chose to favor logical
representations over physical ones, at least when there are no other compelling arguments to
sway the decision either way. That means preferring host names over IP addresses in general.
If you don't have a meaningful host name for the device however, don't make one up -- just
use the IP address until you do have something better.
Avoid irrelevant parts
Often we include things such as the Application Server host name/IP address in URIs. Unless
we are referring to something that is connected directly an Application Server, or that resides
only in an Application Server, the Application Server where the service runs is merely an
implementation detail. Not including it in the URI allows us to move the service to another
Application Server if required (for instance to rebalance the load) and it also allows for
redundant services. For instance, assuming its protocol allows it, a router could be configured
on two separate Application Servers, each one publishing its own copy of the alarms. These
are logically the same and therefore interchangeable, and we can leverage this to provide
improved fault tolerance.
Encoding
Sometimes URIs will need to include some parts that are based on more or less free-form user
input, and in those cases the possibility exists that users will enter special characters which
either are not allowed in URIs at all, or may cause problems with the automated parsing of
your URIs. In those cases, instead of restricting what users can enter (except when it makes
sense, for instance for a slot or port number), it is preferable to escape or encode the user-
entered string. Our preferred mechanism to achieve this is to URL-encode those parts using a
UTF-8 encoding.
Derived (alarm) URIs
There is sometimes a case for generating meaningful URIs that are associated to other existing
(and presumably also meaningful) URIs. This occurs when you publish an alarm that depends
directly on another alarm. A good example are the alarms published by the cycling engine; we
want these alarms to be derived from the base alarms that they relate to, adding a notion of
channels into the mix. Another example are event URIs for events that are closely related to
alarms, for instance an event that pertains to acknowledging an alarm, or switching a router
crosspoint.
The approach that we favor is to add a prefix to the existing alarm (which is less problematic
than adding a suffix). For instance you might get:
cycled:<channelID>:<baseAlarmURI>
event:ack:<relatedAlarmURI>