Overview

This article defines the standards and usage patterns relative to Cordial's implementation. Below, you can find more details on each of the API's functionality and methods.

This document is not meant to provide comprehensive education on REST.

Authentication

Cordial's core APIs use HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

Most REST API clients, such as cURL and Postman, allow you to use your username and password to authenticate HTTP requests with BA. Instead of exposing your login credentials in this manner, your account API key can be passed as the username while the password is left blank. This is similar to how Swagger authenticates your API endpoint access using only the account API key.

It's common practice for REST clients to encode the given credentials in base64 and pass the string within the HTTP request authorization header, similar to this example:

--header 'Authorization: Basic c2VuZGFiZXR0ZXJtZXNzYWdlYW5kYWx3YXlzYmVjb3JkaWFsZW1pcg=='

Access Cordial REST resources via URL

Cordial has two distinct API addresses, so it's important to check which one is associated with your account:

• For accounts located at HTTPS://admin.cordial.io/, the associated API URL is https://api.cordial.io/v2/.
• For accounts located at HTTPS://usw2.admin.cordial.io/, the associated API URL is https://api.usw2.cordial.io/v2/.

The URL structure will generally look like this (example using HTTP):

<path-url><resource-name><query-string>

• <path-url> is the root location for the resources
• <resource-name> identifies the resource location in the directory structure. Examples:
  • /supplements
  • /supplements/cars/fields/vin_number
• <query-string> enables parameters to filter the response. For example, to limit the GET response for this resource to only return attributes of type "string", we would use the following.
  • /supplements/cars/fields?type=string  

Supported methods

Cordial supports four methods. They are POST, GET, PUT, and DELETE. Depending on the resource, one or all methods may apply.

• POST: Creates a new entry in the collection. In some cases, the ID or key is assigned automatically by the collection. In other cases, it is passed as a value within the JSON request body. The ID or key created is usually included as part of the data returned by this operation.
• GET: Retrieves the members of a collection. Typically the response data will include member keys for further navigation when appropriate. In some instances, additional query parameters are available for further filtering the request.
• PUT: Replaces or updates the entire collection with another collection or subset of updated fields.
• DELETE: Removes a member of a collection, typically referenced by an ID or key value.

To learn about each resource and its associated methods and options, you can visit these sections:

• Contact management APIs
• Orders, products, and supplements APIs
• Message creation, delivery, and analytics APIs
• Operations and content management APIs
• Integrations APIs and Webhooks

Rate limits

Cordial reserves the right to impose a rate limit for excessive or abusive API usage. In the case where a rate limit is exceeded, the API will respond with the HTTP status code: 429 Too Many Requests.

Certain client applications may initially attempt each API call before receiving a server authentication response. API calls made in this manner, and those with missing or incorrect authentication data, will be rejected and rapidly consume the rate limit.

The application should reattempt the rejected requests employing an exponential backoff of additional API calls.

Alternatively, preemptive authentication should be enabled when possible. As an example, commonly used Jakarta Commons HttpClient allows users to enable preemptive authentication if desired. Visit the Apache HttpComponents website for the latest HttpClient version and documentation details. Most client applications do not install with preemptive authentication enabled by default, so manual configuration is required.

If rate limiting is encountered under normal circumstances, or if you have a specific use case in mind, contact your Client Success Manager or submit a support request.

Using JSON

Cordial uses standardized JSON for both requests and responses (as opposed to XML). JSON is programmer friendly, and it's the basis of how data is stored and managed in the underlying MongoDB. There are three primary JSON code structures utilized within the APIs.

1. Request body
2. Response header
3. Response body

As an example, the request and response JSON to POST a new contact into the Cordial database might look like the following:

Request body

{
   "email": "tester1@example.com"
}

Response header

{
   "Date": "Tue, 06 Jan 2015 16:57:29 GMT",
   "Server": "Apache/2.4.7 (Ubuntu)",
   "Connection": "keep-alive",
   "X-Powered-By": "PHP/5.5.9-1ubuntu4.5",
   "Content-Length": "44",
   "Content-Type": "application/json"
  }

Response body

{
  "success": true,
  "message": "contact created"
}