API 2.0 Developer Information

Source:

Published:

Keywords: Certain API 2.0, REST, HTTPS, Basic Authorization, RFC 2617, Accept header, 429 error, API rate limit

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

API

Introduction

Certain API 2.0 is a set of REST methods provided as part of the Certain platform.

Developer Info

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 and if 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

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

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

https://host/certainExternal/service/v1/object/accountCode/eventCode/registrationCode

https://host/certainExternal/service/v1/object/accountCode/eventCode/

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.

Each of the path elements is described in the following sections.

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.

An example accountCode is "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.

An example eventCode is "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 page includes examples for details on specifying the Accept header.

Query Parameters

Query parameters are optional.

Query parameters are specified at the end of the registration object path.

Query parameters are specified after a question mark.

Each parameter is separated from the others by an ampersand (&).

Query parameters follow 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

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 500 error.

This issue is particularly for the User Conference business objects.

Example

URL

Url:- https://app.certain.com/certainExternal/service/{ServiceUrl}

An example 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 -

REQUEST BODY- Not Applicable

Filters (Optional)

Results can be filtered by specifying filters(check supported filters).

An example filter-by accountCode is: 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).

An example sort by dateCreated (ascending order) is: 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 -

REQUEST BODY- Not Applicable

POST

HTTP METHOD - POST

URL - https://app.certain.com/certainExternal/service/v1/{service name}/{accountCode}/{eventCode}

HEADERS -

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?

The reason for the rate limit is to ensure fair usage.

The reason for the rate limit is to maintain the stability of the API and services.

Similar limits are common industry-wide.

Similar limits are used 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.

A 429 error indicates too many requests within a short time.

A retry-after suggestion is 2 seconds.

The suggestion includes using an exponential backoff strategy.

5. How does this protect customers?

Enforcing rate limits prevents excessive requests.

Excessive requests 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

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.

Object Summary