Higher Logic Vanilla’s (Vanilla) API v2 supports smart IDs.
- These are specially-formatted placeholders that can transparently lookup resource IDs, based on supported criteria.
⭐️ EXAMPLE: You can use a smart ID in an API request to look up a Category by its URL code. Another example is to use a smart ID to look up a user based on their SSO foreign IDs.
Usage
The basic format of a smart ID is:
“Field” is the property you’re attempting the lookup with, while “value” is its corresponding criteria. Vanilla will attempt to resolve the smart ID to a specific resource and substitute the row’s primary ID in its place.
⭐️ EXAMPLE: Submitting a request to /api/v2/users/$name:baz will ultimately be dispatched by Vanilla as /api/v2/users/15, where 15 is the ID of a user with the name “baz.” Do not put a space between the ":" and the value.
Smart IDs can be used in three areas of a request:
- the path,
- the query,
- and the body.
When received in one of these areas of a request, Vanilla will attempt to look up the corresponding record, based on the criteria provided.
Depending on where the smart ID is used, the resolution of the target record ID is dependent on different criteria.
⭐️ EXAMPLE: If received in the path, the URL will be used to determine what type of record Vanilla is looking up. A request to /api/v2/users/$name:foo will attempt to look up a user with the name “foo,” while a request to /api/v2/categories/$name:foo will attempt to look up a Category with the name “foo.” The same smart ID is used, but the context determines which resource is queried. Similarly, when a smart ID is used in a query or the body of the request, the key of the value is used to resolve the resource. In the case of a smart ID in a query, say /api/v2/discussions?insertUserID=$name:bar, Vanilla will attempt to look up a user with the name “bar” because the associated key is “insertUserID.” The same request could be modified to /api/v2/discussions?categoryID=$name:bar and now a Category with the name “bar” will be used.
📝 NOTE: If a smart ID resolves to multiple rows, or none at all, a fatal error will be generated. A smart ID must resolve to exactly one row.
Supported fields
You can currently use smart IDs with the following resources.
Categories
Categories support smart ID lookup using one of two fields:
- name - The name of a Category.
- urlcode - The URL code of a Category.
Category smart ID examples
📝 NOTE: The following examples are not URL-encoding their smart IDs. You must do that when using them.
// Get discussions by category name.
https://example.com/api/v2/discussions?categoryID=$name:Help
// Get a single category by URL code.
https://example.com/api/v2/categories/$urlcode:support-qna
Users
Users support smart ID lookup using one of three fields:
- name - The name of a user.
- email - The email address of a user. This field is only accessible if the user submitting the request has the ability to view user email addresses.
- A foreign ID from an SSO connection.
$me for the current user
$me can be swapped in for the current session's userID. In the case that a user is a guest and doesn't have an authenticated session, it is equivalent to the guest ID (0).
Here are a few examples:
// Get the current users permissions
https://example.com/api/v2/users/$me/permissions
// Get the current users recent discussions
https://example.com/api/v2/discussions?insertUserID=$me&sort-dateInserted
SSO smart IDs
Given the key for an authentication provider, and the foreign ID of a user connected by that provider, you can resolve a foreign ID to a Vanilla user ID.
⭐️ EXAMPLE: If a site has an authentication provider with a key of “vanillasso,” you could attempt to look up a user with a foreign ID from that provider by using the following smart ID: $vanillasso:1234. Vanilla will attempt a lookup of any users connected from “vanillasso” with a foreign ID of 1234. If one is found, their local user ID will be substituted in place of the smart ID. If no matching user is found, an error is encountered. "authprovider" is to be replaced. If you are not sure which key to use for your authentication provider, check your SSO settings and use the ClientID name.
It can be challenging to figure out the client ID of your SSO provider. Here are a few places to check:
- OAuth: This is your client ID when you edit the connection.
- jsConnect: This is your client ID when you edit the connection.
- SAML: This is usually just the single string "samlsso," but the client ID can be changed.
Here is an example of an endpoint to get a user's info based on their SSO SmartID:
https://valerie.vanillademo.com/api/v2/users/$vanillasso:1234
Roles
Categories support smart ID lookup using the name field.
Role smart ID example
// Fetch a list of admin users.
https://example.com/api/v2/users?roleID=$name:admin
