Concepts
These concepts are commonly used throughout the Rhythm API. They are useful to understand before exploring guides or references for specific APIs.
Tokens
Rhythm's API will accept either tokens generated for a specific user (user tokens), or a token generated for automated, machine-to-machine scripts (M2M tokens).
warning
There is a monthly limit on the number of M2M access tokens you may generate across all your integrations (1,000). If you exceed this limit, you will not be able to issue any more M2M tokens until the next month, which may cause your integrations to fail.
Tokens are valid for 24 hours, so they should be securely cached during that period to reduce usage. Therefore, each application using the Rhythm API should only be using a maximum of 31 M2M tokens per month.
This limit does not apply to the other authorization flows where a user is interactively entering credentials (see below). You should never issue a M2M token for each user login.
Because of the limit on M2M tokens, you should instead use a user token whenever you are accessing the Rhythm API on behalf of a user who has logged in interactively. If a user is entering their credentials, you should use the Authorization Code flow whenever possible. If your application cannot support redirecting the user and must receive user credentials directly, you may instead use the Resource Owner Password flow to generate a user token using an API call (this must be requested at the same time you submit a request for API credentials).
M2M tokens are only appropriate for scenarios such as an automated, recurring jobs, or bulk data operations, where no interactive user is logged in. Because these API calls are being executed by a system with no interactive user, you should be able to cache and reuse a single M2M token for 24 hours.
For more information see the section on authentication.
Users vs. Contacts
A User and a Contact are distinct but related records. A Contact exists in the Rolodex (Contacts & Organizations) app and contains all demographic information. When a member joins, renews, registers, pays, etc. on the Rhythm Portal, all of this information is related to the Contact record.
A User may be thought of as an identity, or as login credentials, that may come from a variety of systems external to Rhythm (Google, Facebook, LinkedIn, etc). A Contact record may be related to one or more Users.
Duplicate Prevention
One member may create multiple Users by logging in with LinkedIn, then Google, then Facebook, but link all of these Users to the same Contact. Since all records in Rhythm are related to the Contact, when they log in to the Rhythm Portal, they always see the same information regardless of which User account they use.
This linkage is established the first time a User logs into the Rhythm Portal. The related Contact ID is stamped on the User metadata and can later be retrieved from any JSON Web Token (JWT) issued for the user as described in the authentication or SSO guide.
Requests
Most requests require a tenantId value passed in the URI. This value identifies the Rhythm tenant you are working against. If you do not know your tenantId, please contact support@rhythmsoftware.com.
Multi-Tenant
For multi-tenant integrations, you must supply the tenantId that is applicable for the current request.
Every request to the Rhythm API requires an HTTP Header called Authorization which is examined to allow or deny the request.
In the next section authentication, we will see how to retrieve an access token for
a user to make API calls on their behalf.
Denied
If you submit a request for a tenantId the user is not authorized to access, or to a URI that does not match any endpoint, your request will be denied.
Many requests also require a contactId value passed in the URI. In most cases, this is the contactId for the user who initiated the API request, which you can extract from the authenticated user's access token.
Responses
Most of the endpoints in the Rhythm API return a single record or item. However, some long-running tasks, such as queries will instead return an identifier that you can use to check the progress of the task. For an example, see the query guide.
Other tasks, such as processing an Order, Invoice, or Payment, will return an executionArn which can be used in the System API > Step Functions to check on the status of these tasks.
Paging
When an endpoint may return many records or items, rather than just returning an array, it will return the results
in the Items property of an object that also contains Count and LastEvaluatedKey properties. The LastEvaluatedKey
can be returned to the same endpoint in the exclusiveStartKey query string parameter to get the next page of results.
Rate Limits
Looping through all pages programmatically may cause you to exceed API rate limits.
Instead, use a query to retrieve all items at once (described below).
Retrieving Multiple Items
The Rhythm API uses three patterns for retrieving multiple items in a single request & response.
| Capability | List | Search | Query |
|---|---|---|---|
| Specify return fields | Yes | Yes | Yes |
| Paged results | Yes | Yes | No |
| Filter results | No | Yes | Yes |
| Complex criteria | No | No | Yes |
| Fields from related types | No | No | Yes |
| Multiple return formats | No | No | Yes |
List
The simplest are lists which are GET endpoints that return a simple JSON array of items. These endpoints do not
have the option to supply custom criteria.
Examples of list endpoints might be listAddressTypes or getUpcomingEvents.
Fields
Like most GET endpoints, you can supply field names in the query string to limit the response size, which can be very useful for client-side javascript or mobile clients.
Search
A search is also a strongly typed POST endpoint which defines preset criteria options you can supply in the body to
change the search parameters. These endpoints return a JSON object which may contain Count, Items, and LastEvaluatedKey
attributes. The Items attribute will be an array containing one page of the items that match all the criteria you
supplied (see Paging above).
Examples of search endpoints might be searchForContacts or searchForEvents.
Query
A query uses multiple POST and GET endpoints. The same endpoints are used to initiate a query regardless of the
type being returned. A query will return a JSON object with the URI of a loosely typed dataset containing all the items
that match the criteria.
Flexible
Query is the most flexible method for retrieving multiple items. With a Query you can:
Define criteria with advanced any or all grouping, nested groups, and a variety of operators.
Return results in json, csv, excel, or another data type you specify.
Use return and criteria fields from multiple types, or multiple apps, within the same query.
To learn more about queries see the Query Guide.