Overview
- Responses
-
- Drupal <=8.3 (existing sites): response bodies use UNIX timestamps (i.e. BC layer active by default)
- Drupal >=8.4 (new sites): response bodies use RFC3339 timestamps
- Requests
-
Timestamp fields can now be sent in a request body in three formats:
- UNIX timestamp (example:
1478422920
) - ISO8601 (
Y-m-d\TH:i:sO
, example:2016-11-06T09:02:00+00:00
) - RFC3339 (
Y-m-d\TH:i:sP
, example:2016-11-06T09:02:00+0000
)
This works on both new sites and existing sites.
- UNIX timestamp (example:
Before
In Drupal 8.0, 8.1, 8.2 and 8.3, all normalized TimestampItem
, CreatedItem
and ChangedItem
values in the JSON, HAL+JSON and other formats are UNIX timestamps. UNIX timestamps do not convey timezones. Many people send back a timestamp specific to their timezone, and then expect it to work correctly. This is very confusing. Turns out just sending a number is not a very clear normalization/serialization of a date + time.
- Response
-
{created:[{value:1478422920}]}
- Request
-
{created:[{value:1478422920}]}
This is an undesirable developer experience for consumers of this data. It's not clear how to interpret the data. It also requires conversion to UTC.
After
In Drupal 8.4, existing sites continue to receive the same response as before: backwards compatibility is maintained.
But new sites built on Drupal 8.4 or later will get this:
- Response: existing site
-
{created:[{value:1478422920}]}
- Response: new site
-
{created:{value:'2016-11-06T09:02:00+0000',format:'Y-m-d\TH:i:sP'}}
(The exact format string is sent as a hint.)
- Request: both existing & new sites
-
{created:{value:'2016-11-06T09:02:00+0000'}}
(No need to send
format
, although it is accepted.)A full list of the serialized data it accepts:
{created:{value:'2016-11-06T09:02:00+0000'}
{created:{value:'2016-11-06T09:02:00+0000',format:'Y-m-d\TH:i:sP'}}
{created:{value:'2016-11-06T09:02:00+00:00'}
{created:{value:'2016-11-06T09:02:00+00:00',format:'Y-m-d\TH:i:sO'}}
{created:{value:1478422920}
{created:{value:1478422920,format:'U'}
And for any of 1–4 above, you can specify a timezone offset — for example:
{created:{value:'2016-11-06T09:02:00+0100'}
. This will then be converted to UTC automatically.
Backwards compatible: existing sites can opt in to the new behavior
Existing sites can opt in to the new behavior by changing the bc_timestamp_normalizer_unix
key's value from true
to false
in serialization.settings
configuration using one of the following mechanisms:
- Use the Configuration API in custom module or integration code.
- Use Drush:
drush config-set serialization.settings bc_timestamp_normalizer_unix FALSE
- Use configuration override
This backwards compatibility layer will be maintained until Drupal 9; in Drupal 9.0 it will be dropped.
Backwards compatibility in tests: BcTimestampNormalizerUnixTestTrait
Use BcTimestampNormalizerUnixTestTrait::formatExpectedTimestampItemValues(123456789)
to generate expectations that automatically respect the aforementioned BC flag. This BC-only, test-only helper is deprecated in Drupal 9 and will be removed before Drupal 10. In Drupal 9, you'll be able to write expectations programmatically like (new \DateTime())->setTimestamp(123456789)->setTimezone(new \DateTimeZone('UTC'))->format(\DateTime::RFC3339)
or just specify an RFC3339 timestamp.