Developer Info

Source:

Keywords: Certain API 2.0, Basic Authentication, HTTP GET, HTTP POST, HTTP DELETE, 429 error, API rate limit

Document ID: https://developer.certain.com/api2docs/developer#split1

Developer Info

Certain API 2.0 is a set of REST methods provided as part of the Certain platform. Certain API 2.0 uses REST methods that are URLs 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, Certain API 2.0 enables new resources to 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. HTTP GET requests are used for retrieval of resources. HTTP POST requests are used to create new resources. 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. 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. The RFC 2617 specification can be found at .

This mechanism is broadly supported by HTTP integration products. This mechanism is also broadly supported 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

Business Object Resource Path Elements

Each resource in Certain API 2.0 is identified by a path. This 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. The following paragraphs describe these path elements.

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. Most browsers will specify XML in their request's Accept header. The examples provide details on specifying the Accept header.

Query Parameters

Query parameters are optional. Query parameters can be specified at the end of the registration object path. Query parameters follow a question mark. Query parameters separate from each other using an ampersand (&) as per the normal HTTP query parameter syntax.

The following parameters are supported:

View the individual objects for more detail on the parameters that are supported per object.

Testing

A REST Test client is recommended. Examples of REST Test clients include Rest Client for Firefox and Postman for Chrome.

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 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). For example, filter results by accountCode. https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?accountCode=Dell

Order By (Optional) - Results can be sorted by specifying orderBy (check supported orderBy). For example, sort results by dateCreated (ascending order). https://app.certain.com/certainExternal/service/v1/Account/Dell/Promotion?orderBy=dateCreated_asc

DELETE

DELETE is supported using the HTTP METHOD - DELETE. REQUEST BODY - Not Applicable. URL - https://app.certain.com/certainExternal/service/v1/{service_name}/{accountCode}/{eventCode} HEADERS - Accept - application/json Username - username Password - password

POST

POST is supported using the HTTP METHOD - POST. REQUEST BODY is applicable.

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", "accountCode": "eventCode": "eventCodeXYZ", "accountCode": "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 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. 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.