CrowdTwist API Best Practices

Future Proofing API Integrations
Data Push API Integrations
TLS Support
API Failover Strategy

 

Future Proofing API Integrations

The CrowdTwist platform is constantly evolving with new changes typically being released to production on a weekly basis. The development organization takes great care to ensure changes are backwards compatible, but certain best practices must be followed to enable the team to move quickly and to support all client initiatives.

The CrowdTwist API uses Javascript Object Notation (JSON) as the data-interchange format for all API endpoints. In order to leverage the latest changes while minimizing disruption to your CrowdTwist integrations there are best practices that are to be followed.
It’s important that the CrowdTwist Engineering team has the ability to add properties to existing JSON objects without causing breaking changes to client API integrations. This enables the team to advance the platform quickly and to better support client needs. Properties should be checked for existence within the JSON object and validation performed for those properties types. Do not validate the JSON object for total number of properties or perform checks for JSON properties that aren’t being used for the integration.

Changes to existing JSON properties (i.e. changing property data types, removing properties, etc) are considered breaking changes. Breaking changes will either be approved by clients using the API or a result in a API version bump.

 

Data Push API Integrations

CrowdTwist Data Push APIs attempt to POST to the client-provided endpoint. Unsuccessful data push requests will be attempted five times an hour for up to eight hours, after which they are recorded in an error log. Your support team can assist in providing an export of failed requests if needed.
 
As a redundancy check, we recommend integrating with the daily batch push files in addition to client-provided API endpoints.

 

TLS Support

- The CrowdTwist application supports the TLS 1.2 protocol
 
The list of supported cipher suites at this time:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (0xc02f)
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (0xc027)
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (0xc013)  
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (0xc030)  
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (0xc028) 
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (0xc014) 
TLS_RSA_WITH_AES_128_GCM_SHA256 (0x9c)      
TLS_RSA_WITH_AES_128_CBC_SHA256 (0x3c)        
TLS_RSA_WITH_AES_128_CBC_SHA (0x2f) 128
TLS_RSA_WITH_AES_256_GCM_SHA384 (0x9d)
TLS_RSA_WITH_AES_256_CBC_SHA256 (0x3d)        
TLS_RSA_WITH_AES_256_CBC_SHA (0x35)
 
If your application does not support at least one of the protocols and cipher suites above, it will not be able to make a connection. Please check to ensure compatibility. Some older languages such as Java 6 do not support TLS versions greater than 1.0. If your application uses an older language without TLS 1.2 support, it will be necessary to upgrade to a newer version of the language. Please contact us if you have any questions about this.

 

API Failover Strategy

The page describes CrowdTwist’s recommendations when CrowdTwist APIs are down. When the CrowdTwist API is down or there are network issues, clients will start receiving 5XX response. In such scenarios the responsibility falls on the requestor to ensure they handle 5XX errors gracefully and ensure their own website is not affected. Clients are responsible to provide appropriate messaging to end users in this case. Clients should determine backoff strategies that suit their platform, when CrowdTwist APIs are down. As a rule of thumb clients should periodically check to see if APIs are back up.

Idempotent vs Non-idempotent APIs

  • For an API to be idempotent, clients can make that same call repeatedly, without changing the state of the system, even if the output of the call might differ.
  • Non-idempotent requests on the other hand will change the state of the system and should not be batched. Depending on the type of request, some non-idempotent API requests can be queued and retried and for other requests, clients have to send a completely new request, when the API is back up. 

Requests which support batch
Requests which can be batched also support queuing. When clients start receiving 5XX from CrowdTwist, clients can start with queuing requests. If CrowdTwist platform is down for substantial period of time, clients should switch to batching. If batch files are used, clients need to send all requests in batch files including any requests that error out to ensure requests are processed correctly. Clients are responsible for picking the strategy that works best for them. Below are CrowdTwist’s recommendations for requests which support batch.

Request Type  Timeout Notes
  • User Create
 Idempotent 30 seconds
  • User create requests can be processed out of order. In most cases they are not time sensitive.
  • CrowdTwist recommends clients batch user create requests to a file when CrowdTwist API is down.
  • Commerce v2

·

    • Purchase
    • Fulfillment
    • Returns
 Idempotent 10 seconds
  • For commerce v2 requests, when clients start receiving 5XX errors, it will affect user’s experience during checkout. Crowdtwist recommends clients to queue up requests and retry periodically.If the API continues to be down for sustained periods of time then clients should stop calling the CrowdTwist API, write all the requests for the day to a batch file and send the file to CrowdTwist at the end of the business day. 

Requests which can be queued
These requests are POST requests and are non-idempotent i.e. when a request identical to the previous one is made, the response from the API will not be the same. These requests do not support batch processing. The order in which the requests are made needs to be preserved to maintain data integrity.

Request Type Timeout Notes
  • Reward Redemption 
  • Code Redemption Submit
  • Survey Submit
  • User Activity Credit
 Non Idempotent 30 seconds
  • Clients are recommended to queue the requests and retry whenever CrowdTwist API is up. In case of the CrowdTwist API being down clients are responsible for appropriate error messaging and handling any 5XX errors gracefully.
  • User Update
 Non Idempotent 30 seconds
  • User update is a PUT request and needs to be queued and retried when the CrowdTwist API is up. Clients are responsible for handling user update failures with appropriate messaging.

Requests which need to be tried at a later time
These are GET requests and authorization requests. Once clients start receiving 5XX errors,they should stop sending requests to CrowdTwist API and handle the 5XX errors on their side with appropriate messaging. Clients should send requests periodically to check if the CrowdTwist API is up. Once the API is up clients have to send new requests.

Request Type Timeout Notes
  • Authorization
 Not applicable 30 seconds
  • When clients are receiving 5XX on auth requests it falls on the client to handle the response gracefully and provide users with appropriate messaging. Auth requests cannot be retried and a new request has to be made when the CrowdTwist API is up.
  • Get Activity
  • Get Rewards
  • Get Survey
  • Get Code Redemption
  • Get User Points
  • Get User Activity History
 Not applicable 30 seconds
  • Clients are responsible for handling Get requests which return 5XX, with appropriate messaging. Get requests have to be made once the API is back up.