Timestamps (v2 vs. v3)

This documentation uses the term "timestamp" to refer to a combined representation of date and time that refers to a specific moment in time with some means to avoid timezone ambiguity. The most reliable way to avoid timezone ambiguity is to explicitly specify the timezone in the timestamp. When not specified, there must be a way to assume an implied timezone.

Note that subsequent major versions of the Fetch API interpreted timestamps differently.

Fetch API v3 is preferred

The current and preferred version of the Fetch API is v3. It supports the internationally recognized ISO 8601 standard for specifying a timestamp as a combination of year, calendar date, time of day, and timezone. This aspect of the ISO 8601 standard is described in the following authoritative sources:

• ISO 8601 Date And Time Representations (paywall)
• Wikipedia ISO 8601 Combined Date And Time Representations

For example, 2024-02-01T06:05:58.3789726-05:00 specifies a date and time in a zone five hours behind UTC.

ISO 8601 "T" delimiter

Over the years, the ISO 8601 standard has become more strict. The "T" character separating the date and time portions of the timestamp was not always required but is required today whenever a timestamp specifies more than just a date. Although some systems have a practice of substituting the "T" with a space character for readability, this is not compliant with the standard. Fetch API v3 expects full compliance.

API Versioning Principles

The Fetch API uses a semantic versioning scheme. We take great care as to ensure that any changes made to the api endpoints and models do not affect integrators without a major version bump. As time progresses, we make incremental feature enhancements to existing versions as necessary. This can be found as new endpoints or additional model properties that get included overtime.

Differences between v2 & v3

Currently Fetch API has two versions available, v2 and v3. The latest version (currently v3) is the preferred version as it properly supports UTC based time, with ISO 8601 compliance, which we have found is more reliable for integrations that consume our API. Support for v2 is planned to sunset at some time in the future. All future versions of the api will be handled with a date time format of v3.

In more technical terms, the difference between v2 and v3 is that v2 dates are considered local time in DateTime (2024-02-01T06:05:58.378), while v3 dates are DateTimeOffset (2024-02-01T06:05:58.3789726-05:00) to allow for UTC time based comparison.

Example of data field changes between v2 and v3

The following example objects highlight the expected changes between v2 and v3 API versions. The requests used here represent the same Client ID and User name for the token, so the source data can be considered the same.

Example v2

curl --location 'https://fetch.yellowdogsoftware.com/api/v2/items?orderBy=sku&filter=lastUpdated>=20240118'

Response body

[
  {
    "id": "8f51224d-f36b-1410-82e8-00371620ba36",
    "description": "DELETE_ME_LATER_PLS: 71931-13092",
    "sku": "24662FAKESKU27259",
    "lastUpdated": "2024-02-01T06:05:58.378Z",
    ...(other fields removed for brevity)
  }
]

Example v3

curl --location 'https://fetch.yellowdogsoftware.com/api/v3/items?orderBy=sku&filter=lastUpdated>=20240118'

Response body

[
  {
    "id": "8f51224d-f36b-1410-82e8-00371620ba36",
    "description": "DELETE_ME_LATER_PLS: 71931-13092",
    "sku": "24662FAKESKU27259",
    "lastUpdated": "2024-02-01T06:05:58.3789726-05:00",
    ...(other fields removed for brevity)
  }
]

Differences highlighted

• v2 lastUpdated field reflects the local time value with Z at the end: 2024-02-01T06:05:58.378Z. This is not ISO compliant. ISO 8601 expects a Z suffix to indicate the UTC time zone.
• v3 lastUpdated field reflects the full ISO 8601 representation as date and time with a timezone offset: 2024-02-01T06:05:58.3789726-05:00