API V2 Enhancements

 

Platform Status:
 
The Engage Engineering team has been rolling out a number of enhancements for monitoring and stability fixes of over the last few weeks for the Engage platform.  A number of core stability and performance issues have been resolved; however, there are a few intermittent issues remaining in our backlog that we are continuing to address.
 
There are 2 changes to be aware of that we will be rolling out to  Engage API v2.  These changes will help us properly identify any remaining stability issues in the platform, as well as enable us to be much more proactive when future issues occur.
 
There will be no service interruptions or downtime required for this.
 
1. Moving to proper HTTP Status codes in API v2 responses
We will begin an incremental rollout that will involve correcting the HTTP Status Codes returned on various error responses from API v2.
 
HTTP-4XX errors should be exclusively for "errors in the client request".
HTTP-5XX errors should be exclusively for "errors on the Engage platform".
 
Currently, most of our errors that should be 5XX are being returned as 4XX.  This makes it difficult to determine, at a platform level, whether issues are being caused by the client request, or the platform itself.
 
We also have a number of errors that are returning the improper 4XX error, which makes it difficult to proactively assist our customers.
 
 
2. Error response object in API v2 responses
We will begin an incremental rollout that will add some additional fields to the response object received whenever an error is returned.
 
These new fields will include:
- "requestId": a unique identifier for the request as it traverses through our microservice architecture.  In the future, please reference this "requestId" value when submitting support tickets, as we will use it to identify the full transaction log trace in our monitoring systems.  This will allow us to significantly improve the speed at which we troubleshoot customer issues.
 
- Additional fields will also be added to provide finer grained detail on the specific cause of the error.
 
 
What these changes mean for API users:
Change #1: HTTP Status Codes
- As a best practice, API consumers should only be coding against "success" and "failure" (as opposed to hard-coding against HTTP status codes).
- We recommend changing to this approach.  If you are hard-coded against specific status codes, you may see some impact on your API integration as the response codes change.  Please reach out to Customer Support if you require assistance with this change.
 
Change #2: New Error Response Fields
- These are new fields being  added, which should not affect existing fields.  Therefore, existing API integrations should not be affected.
 
 
Timeline:
These changes will be rolled out incrementally, starting  Thursday May 17, and continuing for 2-3 weeks.

Platform Status:   The Engage Engineering team has been rolling out a number of enhancements for monitoring and stability fixes of over the last few weeks for the Engage platform.  A number of core stability and performance issues have been resolved; however, there are a few intermittent issues remaining in our backlog that we are continuing to address.   There are 2 changes to be aware of that we will be rolling out to Engage API v2.  These changes will help us properly identify any remaining stability issues in the platform, as well as enable us to be much more proactive when future issues occur.   There will be no service interruptions or downtime required for this.

1. Moving to proper HTTP Status codes in API v2 responses We will begin an incremental rollout that will involve correcting the HTTP Status Codes returned on various error responses from API v2.   HTTP-4XX errors should be exclusively for "errors in the client request". HTTP-5XX errors should be exclusively for "errors on the Engage platform".   Currently, most of our errors that should be 5XX are being returned as 4XX.  This makes it difficult to determine, at a platform level, whether issues are being caused by the client request, or the platform itself.   We also have a number of errors that are returning the improper 4XX error, which makes it difficult to proactively assist our customers.

2. Error response object in API v2 responses We will begin an incremental rollout that will add some additional fields to the response object received whenever an error is returned.   These new fields will include: - "requestId": a unique identifier for the request as it traverses through our microservice architecture.  In the future, please reference this "requestId" value when submitting support tickets, as we will use it to identify the full transaction log trace in our monitoring systems.  This will allow us to significantly improve the speed at which we troubleshoot customer issues.   - Additional fields will also be added to provide finer grained detail on the specific cause of the error.

What these changes mean for API users: Change #1: HTTP Status Codes - As a best practice, API consumers should only be coding against "success" and "failure" (as opposed to hard-coding against HTTP status codes). - We recommend changing to this approach.  If you are hard-coded against specific status codes, you may see some impact on your API integration as the response codes change.  Please reach out to Customer Support if you require assistance with this change.   Change #2: New Error Response Fields added

Timeline:Thursday May 17