Concepts

These concepts are commonly used throughout the Rhythm API. They are useful to understand before exploring guides or references for specific APIs.

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. For an example, see the member lookup guide.

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.

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.