IDs in the API

Every Ampbase id is a ULID: 128 bits, written as 26 characters of Crockford base32. Some kinds of id carry a short prefix ahead of the ULID, so you can tell a config's id from a rollout's at a glance.

A policy is a config, so its id is a config's. Copy ids exactly as the API or the dashboard gives them to you, prefix included.

In JSON

The API speaks Connect, and its JSON carries every id as the text above, in requests and responses alike:

{
  "orgId": "01JBQ0Z5M6V3T8K2R4N7P9W1XA",
  "channelId": "01JBQ0Z5M6V3T8K2R4N7P9W1XB",
  "configId": "cfg-01JBQ0Z5M6V3T8K2R4N7P9W1XC"
}

• An id with the wrong prefix, or none where one is expected, is refused with invalid_argument and a message naming the field. A rollout's id sent where a config's is expected fails the request rather than being read as the wrong thing.
• An empty string leaves an optional id unset, the same as leaving the field out.
• Field names may be written in either camelCase or snake_case. Responses use camelCase.

In binary protobuf

Over binary protobuf, an id field is an ampbase.ulid.v1.ULID message, not a string. It holds the 16 bytes of the ULID in two fixed64 fields: hi is the first eight bytes, lo the last eight, each read big-endian. There is no prefix on the wire. The field's type says what kind of id it is.

message ULID {
  fixed64 hi = 1;
  fixed64 lo = 2;
}

JSON also accepts this form, as an object with hi and lo as decimal strings, though JSON responses always use the text form.

A few request fields, org_id and channel_id among them, are plain strings holding the bare ULID text. Their JSON looks the same as a typed id's.