The API code switchover seems to have worked pretty well judging from the lack of any complaints. Now it’s time to move to continuous improvement mode.
The first change we’re going to do is quite simple. Before, when we returned datetimes we would not specify the timezone and it would be in Mountain Time (see #2267). After the change, we will specify the timezone and use UTC for the timezone.
That change is a pretty minor one, but it gives us the opportunity to test out the new API changing technical policy. Here’s a reminder of how it works.
- When we deploy a change to the API, we’ll pick a future date to switch over to the new behavior. This is going to be one month from today 8/24/2015.
- Before the switchover date, we return an HTTP header to indicate that the API will be changing. The name is X-API-DEPRECATED and the value is the switchover date in YYYYMMDD format. So for this change, we will return “X-API-DEPRECATED: 20150824”
- Clients can start using the new API before the switchover date using the X-API-FUTURE header. The value should be the date of the API that you want to use, also in YYYYMMDD format. If the X-API-FUTURE date is >= the switchover date then the new API code will be used. So you can send “X-API-FUTURE: 20150824” to get the new behavior ahead of time.
