CrowdTwist API Best Practices

Overview

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.

Future Proofing API Integrations

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 end point.  If the first POST fails, the API will queue and retry up to five times.  After five attempts the API call fails.
 
As a redundancy check, we recommend integrating with the daily batch push files in addition to client provided API end points.

TLS Support

The official list of CrowdTwist supported TLS protocols is TLS 1.1, TLS 1.2, and TLS 1.3 (not yet released).
 
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.0 support, it will be necessary to upgrade to a newer version of the language. Please contact us if you have any questions about this. We will send more information and reminders as the cutoff date for TLS 1.0 support comes closer.

SFTP Connections

CrowdTwist is updating the cipher libraries allowed in SSH and sftp connections at the end of the 2017 calendar year. Beginning in January 2018, the following protocols will be supported:
 
KexAlgorithms curve25519-sha256@libssh.org,diffie-hellman-group-exchange-sha256
 
Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr
 
MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com,umac-128-etm@openssh.com,hmac-sha2-512,hmac-sha2-256,umac-128@openssh.com
 
If your sftp client does not support at least one element from each of the above groups, it will cause your connection to fail.