Introduction
Certain API 2.0 is a set of REST methods provided as part of the Certain platform.
The REST methods are URLs that are invoked over the Internet using HTTPS.
Each URL identifies the path to one or more business object resources.
The URLs enable retrieval of a single business object resource or a list (collection) of these resources.
Depending upon the type of business object, new resources can also be created, updated or deleted.
A valid username and password must be specified with the request to use Certain API 2.0.
The username and password are authenticated against the database of authorized users for the resource.
After successful authentication, access authorization is checked for the resource.
If satisfied, the requested operation is performed.
Certain API 2.0 uses standard HTTP method semantics.
Retrieval of resources is requested with HTTP GET.
New resources are created with HTTP POST.
Existing resources can be updated with HTTP POST.
Resources can be deleted with HTTP DELETE.
The specific operation and their options depend on the type of business object resource.
Standards Compliance
Basic Authentication is required for Certain API 2.0 requests to be made over HTTPS.
Username and password are provided in the request using the Basic Authorization header as defined in RFC 2617 by the IETF.
This specification can be found at http://www.ietf.org/rfc/rfc2617.txt.
This mechanism is broadly supported by HTTP integration products and by web browsers.
It provides a secure method of request authentication when implemented with the HTTPS protocol.
Sample URLs
Generic REST URLs
- Generic REST URL: https://host/certainExternal/service/v1/object/accountCode/eventCode/registrationCode
List (Collection) of Records
- List (Collection) of Records: https://host/certainExternal/service/v1/object/accountCode/eventCode/
Business Object Resource Path Elements
- Host is your configured domain.
- AccountCode is specified in the Certain application when an account (or sub-account) is created. It is a customer-defined value with meaning to the business entity or department that is conducting events. For instance, "marketing".
- EventCode is specified in the Certain application when an event is created. It is a customer-defined value that should have meaning to the business in relation to the specific event. For instance, "CPUG2013".
- RegistrationCode is automatically generated for each registration created for an event.
Content Type
- The GET method will return XML or JSON based on the Accept header provided by the caller.
- If no Accept header is provided, JSON format will be returned.
- Note that most browsers will specify XML in their request's Accept header.
- See the examples for details on specifying the Accept header.
Query Parameters
Query parameters are optional and can be specified at the end of the registration object path, following a question mark and with each parameter separated from the others by an ampersand (&), as per the normal HTTP query parameter syntax.
The following parameters are supported:
- filterBy — only include the data that meets the specified filter criteria.
- filterType — determines whether the filters are "AND" or "OR" conditions: filterType=AND/OR, defaults to AND.
- orderBy — order the returned data by the specified field.
- pageControls — specifies the subset of the selected records to return.
- max_results — the maximum number of results to return.
- includeList — include additional data not returned in the default response.
- prohibitedList — exclude data returned in the default response.
- listFields — only return a specified subset of fields; only applies to the Registration object (see the Registration: Get reference for more information).
View the individual objects for more detail on the parameters that are supported per object.
Testing
We recommend using a REST Test client such as Rest Client for Firefox or Postman for Chrome.
Testing using a web browser while also logged into Certain can result in a 500 error, particularly for the User Conference business objects.
Example
Url: https://app.certain.com/certainExternal/service/{ServiceUrl} e.g. for account service, serviceUrl is v1/Account/{accountCode}/{eventCode}. If accountCode = Dell and eventCode = Promotion, then the URL will be https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion
GET
- HTTP METHOD - GET
- URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}
- HEADERS - Accept: application/json
- Username: username
- Password: password
- REQUEST BODY - Not Applicable
Filters (Optional) — Results can be filtered by specifying filters (check supported filters). e.g. filter results by accountCode, then the url will be https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?accountCode=Dell
Order By (Optional) — Results can be sorted by specifying orderBy. e.g. sort results by dateCreated (ascending order) then the url will be https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?orderBy=dateCreated_asc
DELETE
- HTTP METHOD - DELETE
- URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}
- HEADERS - Accept: application/json
- Username: username
- Password: password
- REQUEST BODY - Not Applicable
POST
- HTTP METHOD - POST
- URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}
- HEADERS - Accept: application/json
- Content-Type: application/json
- Username: username
- Password: password
- REQUEST BODY - The following JSON payload is an example:
{
"accountCode": "accountCodeXYZ",
"eventCode": "eventCodeXYZ",
"speakerCode": 477,
"firstName": "firstNameXYZ",
"middleName": "middleNameXYZ",
"lastName": "lastNameXYZ",
"pic": "picXYZ",
"bio": "bioXYZ",
"email": "emailXYZ",
"organization": "organizationXYZ",
"isActive": true
}
Note: API supports json and xml both types of contents; the example above uses json type.
API Rate Limit Enforcement FAQ
1) What is the API rate limit? The rate limit is 20 concurrent connections.
2) Why is there a rate limit? The rate limit ensures fair usage and maintains the stability of the API and services. Similar limits are common industry-wide to prevent service abuse and ensure reliability.
3) What will happen if I exceed the limit? The system will return a 429 error. The 429 error means too many requests were sent in a short time.
4) What is a 429 error? A 429 error is an HTTP status code for too many requests within a short time. A retry after 2 seconds is suggested. An exponential backoff strategy is recommended.
5) How does this protect customers? Enforcing rate limits prevents excessive requests that could slow down or disrupt service for all users.
6) How do I avoid hitting the rate limit? Monitor API usage. Implement a retry mechanism with a backoff strategy. Avoid concurrent requests that could trigger the rate limit.
7) Developer best practices for managing API rate limits:
- Implement Exponential Backoff: Gradually increase the wait time after a 429 error to avoid further congestion.
- Monitor and Optimize API Calls: Review integration for minimal API calls; batch or cache responses when possible.
- Handle 429 Errors Gracefully: Design systems to log 429 errors, retry after the specified time, and notify users if delays occur.
- Queue Requests: Use a queueing mechanism to distribute requests over time.
- Parallelism Controls: Limit concurrent requests to stay within the rate limit.
- API Usage Monitoring: Set up real-time monitoring for proactive rate limit management.
8) What if I need more concurrent connections? Contact your customer success manager to discuss your use case.
9) Does the rate limit affect all customers? Yes, this applies to all API users to ensure fair usage.
10) Will this rate limit be adjusted in the future? Limits may be adjusted based on overall system health and customer needs.
11) Who can I contact if I have more questions? Please reach out to your customer success manager.