The Two Feed Identifiers

Feeds have two properties that we regularly interact with when we're talking to the Adafruit IO API: Name and Key.

Name

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:

  • Temperature
  • door one
  • 99 Red Balloons
  • books_I_would_like_to_read_before_2022

Key

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:

  1. 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 "-".
  2. Collapse whitespace and replace with "-".
  3. Collapse all instances of "-" into a single "-" and remove them from the beginning and end of the string.
  4. Make the whole thing lowercase.

It's also important to note that when you change a Feed's Name the Key will also update. We keep Keys in sync with Names whenever a Feed is updated.

Keys are handy because they let us use a human friendly URL when communicating with the AIO API. For example, https://io.adafruit.com/abachman/feeds/beta-test and abachman/f/beta-test are nicer and easier to remember than https://io.adafruit.com/abachman/feeds/588995 or abachman/f/588995.

This guide was first published on Jul 15, 2016. It was last updated on Jul 15, 2016. This page (The Two Feed Identifiers) was last updated on Aug 15, 2019.