Interval

Description

The concept of an interval in API documentation is crucial for representing a specific period of time. This interval is typically defined by two key components: the start and the end of the time period. These components are not just abstract concepts but are detailed through two distinct objects within the API structure. Each of these objects includes a dateTime and a corresponding timeZone, ensuring a precise and context-aware representation of time.

In practical scenarios, such as scheduling flights, the significance of including time zones becomes evident. Flights are events where the time zone can dramatically change between the departure (takeoff) and the arrival (landing). For instance, a flight may depart from New York (Eastern Time Zone) and arrive in London (Greenwich Mean Time Zone). By explicitly stating the time zones in both the start and the end objects of the interval, the API can accommodate these shifts, allowing for accurate scheduling and time management.

Furthermore, the interval concept incorporates the idea of inclusivity and exclusivity in its time range. An inclusive start (inclusiveStart) means that the event timeline includes the exact starting moment as defined by the dateTime. For example, if a conference is scheduled to start at 9 AM, an inclusive start implies that the conference's activities begin precisely at this time.

Conversely, an exclusive end (exclusiveEnd) indicates that the event concludes right before the specified end time. Continuing with the conference example, if it is scheduled to end at 5 PM, the exclusive end suggests that the conference activities stop just before reaching 5 PM. This distinction is vital for preventing overlaps in scheduling and ensuring clear boundaries between consecutive events or activities.

By integrating these detailed specifications into the interval object, the API provides a robust and flexible framework for time management, applicable to a wide range of scenarios, from simple meeting schedules to complex, multi-timezone events like international flights.

Schema

Name	Type	Description
inclusiveStart	Object	An object with dateTime and timeZone, marking the beginning of the event.
inclusiveStart.dateTime	String	A string representing the start date and time of the event in ISO 8601 format.
inclusiveStart.timeZone	String	A string representing the time zone of the start dateTime (e.g., "UTC", "America/New_York").
exclusiveEnd	Object	An object with dateTime and timeZone, marking the end of the event.
exclusiveEnd.dateTime	String	A string representing the end date and time of the event in ISO 8601 format.
exclusiveEnd.timeZone	String	A string representing the time zone of the end dateTime (e.g., "UTC", "America/Los_Angeles").

Example

{
    inclusiveStart: {
        dateTime: "2024-03-01T16:00:00", // Start dateTime in ISO 8601 format
        timeZone: "America/New_York"     // Start timeZone
    },
    exclusiveEnd: {
        dateTime: "2024-03-02T07:00:00", // End dateTime in ISO 8601 format
        timeZone: "Europe/London"        // End timeZone
    }
}