Feeds have two properties that we regularly interact with when we're talking to the Adafruit IO API: Name and Key.
The Name is the user provided name for this Feed. It should be a "human readable" descriptive term that helps you find your Feed in the web-based user interface and keep track of which code is talking to what feed.
The rules for Feed names are:
- A Feed Name MUST include at least one ASCII letter.
- A Name MAY include any upper or lower case ASCII letters, numbers, spaces, dashes, or underscores (" ", "-", or "_", respectively).
- A new Feed Name MAY NOT be the same as an existing Feed's Key if the Feeds are in the same group. By default, all newly created Feeds are part of the Group whose name matches your username.
- Names are case-sensitive. This means "Blender" and "BLENDER" are treated as two different Names.
Names are helpful because they let us associate a human friendly word with our data. We see names when we browse io.adafruit.com on the web and when we get Feed records from the HTTP API. We use names when subscribing or publishing to a Feed with the MQTT API.
Some examples of valid, possibly useful names are:
99 Red Balloons
The Key is a system-generated, URL-safe identifier based on the given Feed Name that can be used in API requests to refer to a particular Feed. Keys are generated based on the Name given when the Feed is created and follows strict rules. The rules for Feed keys are simple:
- A Feed Key MAY ONLY contain lower case ASCII letters, numbers, and the dash character ("-").
- Two Feeds in the same Group may not have the same Key.
These rules in combination with the default Group all Feeds are added to means means a new Feed cannot be created if it will use a duplicate Key and a Feed's Name cannot be modified if the new Name will produce a Key that conflicts with another Feed in any of the Feed's Groups.
The rules Adafruit IO uses to generate Keys from Names are roughly:
- Remove formatting. This step requires a lot of discrete operations, but boils down to transliterating Unicode to ASCII and replacing any non-URL safe characters with "-".
- Collapse whitespace and replace with "-".
- Collapse all instances of "-" into a single "-" and remove them from the beginning and end of the string.
- Make the whole thing lowercase.
It's also important to note that when you change a Feed's Name the Key will not automatically update. If you would like to keep the Key in sync with the Name, you'll need to update both of the attributes.
Keys are handy because they let us use a human friendly URL when communicating with the AIO API. For example,
abachman/f/beta-test are nicer and easier to remember than