Preferred Response Datetime Format & Timezone Headers

Overview

The X-Preferred-Response-Datetime-Format header enables developers to customize the format of date attributes in API responses to meet their specific needs and system requirements. This flexibility ensures that date and time values are returned in a format that is both easily readable and compatible with various programming languages and platforms. It is especially beneficial for developers handling internationalization, allowing them to choose formats with time zone information or region-specific conventions. By offering multiple datetime formats, the API enhances usability and integration across diverse environments.

If the X-Preferred-Response-Datetime-Format header is not specified or an unsupported format is provided, the default format timestamp will be used.

Supported Date Formats

1. ISO 8601

A standard, human-readable format that includes time zone information, widely used and supported across various platforms and programming languages (e.g, 2024-08-04T14:22:01Z).

1curl https://api.payiano.com/v1/payment_links \ 2 -H "Authorization: Bearer ACCESS-TOKEN" \ 3 -H "X-Preferred-Response-Datetime-Format: iso8601"

2. Unix Timestamp

A numerical representation of the number of milliseconds since the UNIX epoch January 1, 1970, 00:00:00 UTC , ensuring high precision. Commonly used in systems where high precision and compact representation are required (e.g, 1722572118554).

1curl https://api.payiano.com/v1/payment_links \ 2 -H "Authorization: Bearer ACCESS-TOKEN" \ 3 -H "X-Preferred-Response-Datetime-Format: timestamp"

3. Compact

The compact datetime format is designed for scenarios where both readability and a concise representation are essential. This format represents dates and times in a way that’s easy for users to read at a glance, while also retaining necessary details like the year, month, day and time of day in a 12-hour format. The compact format follows the structure M d, Y h:i A (e.g., Aug 04, 2024 02:22 PM).

1curl https://api.payiano.com/v1/payment_links \ 2 -H "Authorization: Bearer ACCESS-TOKEN" \ 3 -H "X-Preferred-Response-Datetime-Format: compact"

Timezone Customization

The API also supports the X-Preferred-Response-Timezone header, allowing developers to specify the timezone for datetime values in API responses. When this header is provided, all datetime values will be adjusted to the specified timezone, offering further flexibility for international applications. The header accepts IANA timezone identifiers (e.g., Africa/Cairo, America/New_York, Europe/Berlin).

This additional customization ensures that date and time values in API responses align with the user’s preferred timezone, eliminating the need for client-side adjustments.

If the X-Preferred-Response-Timezone header is not specified, the default timezone is UTC .
1curl https://api.payiano.com/v1/payment_links \ 2 -H "Authorization: Bearer ACCESS-TOKEN" \ 3 -H "X-Preferred-Response-Timezone: Africa/Cairo"

By combining the X-Preferred-Response-Datetime-Format and X-Preferred-Response-Timezone headers, developers can tailor datetime values to meet both format and timezone preferences, ensuring compatibility across diverse environments and enhancing overall API usability.

For webhook events and payloads, datetime attributes will always be sent in UTC timezone in UNIX timestamp format, regardless of the X-Preferred-Response-Datetime-Format or X-Preferred-Response-Timezone headers. This approach maintains consistency across all webhook payloads, ensuring that developers can reliably parse and handle date and time values without needing to account for multiple formats or timezones. By standardizing the datetime format and timezone for webhooks, the API simplifies integration and reduces potential errors, making it easier for developers to work with event-driven architectures.