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. These 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.
In order to use Certain API 2.0, a valid username and password must be specified with the request. 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 access authorization is satisfied, the requested operation is performed.
Certain API 2.0 uses standard HTTP method semantics. Retrieval of resources is requested with an HTTP GET. New resources are created with an HTTP POST. Existing resources can be updated with HTTP POST. Existing 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 - Certain API 2.0 requires requests 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. This mechanism provides a sufficiently secure method of request authentication when implemented with the HTTPS protocol.
Sample URL's
Generic REST URLs
- Specific Record:
- List (Collection) of Records:
Business Object Resource Path Elements
Each resource in Certain API 2.0 is identified by a path. The path is similar to the naming of files in directory trees on a computer.
The path to a specific business object resource is specified as /accountCode/eventCode/registrationCode. The path to the list (collection) of business objects for an event is /accountCode/eventCode.
Host
The host is your configured domain.
AccountCode
The accountCode is specified in the Certain application when an account (or sub-account) is created. The accountCode is a customer-defined value. The accountCode should have some meaning to the business entity, or the department within a business entity, that is conducting events. For instance, "marketing".
EventCode
The eventCode is specified in the Certain application when an event is created. The eventCode is a customer-defined value. The eventCode should have some meaning to the business in relation to the specific event. For instance, "CPUG2013".
RegistrationCode
The registrationCode is automatically generated for each registration created for an event.
Content Type
The GET method will return XML or JSON based on the request 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. Query parameters follow a question mark. Query parameters separate each parameter from the others using an ampersand (&). This syntax matches 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 - nnn where nnn is 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
A REST Test client is recommended. Rest Client for Firefox is one example. Postman for Chrome is another example.
Testing using a web browser while also logged into Certain can result in 500 error. This issue can occur particularly for the User Conference business objects.
Example
Url:- https://app.certain.com/certainExternal/service/{ServiceUrl}
For account service, serviceUrl is v1/Account/{accountCode}/{eventCode}. If accountCode = Dell and eventCode = Promotion, then url will be: https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion
GET
HTTP METHOD - GET REQUEST BODY - Not Applicable
Headers: Accept - application/json Username - username Password - password
Filters (Optional) - Results can be filtered by specifying filters. The filter list must use supported filters. For example, filter results by accountCode, 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. The orderBy list must use supported orderBy. For example, sort results by dateCreated (ascending order), the url will be: https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?orderBy=dateCreated_asc
DELETE
HTTP METHOD - DELETE REQUEST BODY - Not Applicable
Headers: Accept - application/json Username - username Password - password
URL - https://app.certain.com/certainExternal/service/v1/{service_name}/{accountCode}/{eventCode}
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 - { "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 type of contents. The example given above uses json type.
API Rate Limit Enforcement FAQ
1. What is the API rate limit?
20 concurrent connections
2. Why is there a rate limit?
To ensure fair usage and maintain 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 ("Too Many Requests"). Retry after a specified time.
4. What is a 429 error?
A 429 error is an HTTP status code for too many requests within a short time. We suggest a retry after 2 seconds and use an exponential backoff strategy.
5. How does this protect customers?
Enforcing rate limits prevents excessive requests. Preventing excessive requests reduces service slow down or service disruption 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 queuing 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?
We may adjust limits 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.