Jump to research

Composed by

Profile picture

V. J.

Views

195

Version history

V. J., 577d ago

June 20, 2023

What's the best practice way to accept dates and datetimes in an api?

During my research, I examined various Reddit discussions on handling dates and datetimes in APIs and programming languages like Python, Julia, and PowerShell. The majority of these discussions revolved around specific use cases, libraries, and user experiences. The sources had varying degrees of relevance to the original query, and there wasn't a clear consensus on the best practice for accepting dates and datetimes in an API. However, some recommendations and practices did emerge from the discussions.

Have an opinion? Send us proposed edits/additions and we may incorporate them into this article with credit.

Words

511

Time

4m 13s

Contributors

282

Words read

42.2k

Using ISO Format and UTC Time

One common recommendation for handling dates and datetimes in APIs is to use the ISO format, particularly UTC time, as the universal data exchange format. This approach helps avoid potential issues with using local time zones, such as daylight saving time changes and inconsistencies between different time zones. Following this practice ensures that dates and times are consistently represented and reduces the likelihood of errors or misinterpretations. Example: "One user suggests using the ISO format, particularly UTC time, as the universal data exchange format for dates and times in APIs."

Using Libraries for Date and Time Handling

Some Reddit users shared their experiences and preferences for using various libraries to handle dates and times in different programming languages. For example, in Python, the Arrow, Delorean, and Pandas libraries were recommended. These libraries can simplify the handling of dates and times and offer additional functionality compared to the built-in date and time handling methods. Example: "Arrow and Delorean are consistently recommended libraries in the responses."

Using Timezone-Aware Datetimes

Another suggestion is to always use timezone-aware datetimes when working with dates and times, as this can help avoid issues related to timezone offsets and daylight saving time changes. By using timezone-aware datetimes, you can perform operations and comparisons regardless of the timezones they are in, ensuring consistency and reducing the potential for errors. Example: "Always creating timezone-aware datetimes."

Handling Dates in DataFrames

For handling dates in DataFrames, especially in Julia, it is recommended to convert the date format from a string to a date format when importing data or after importing it. This ensures that the dates are correctly sorted and avoids any unexpected results. Example: "To sort the values chronologically, the user has to convert the format of the DateField from a string to a date format."

Handling Dates in Power Query

In Power Query, one user suggested using the "#datetime" function with hours, minutes, and seconds added to the datetime value. Another user recommended using the "#date" function instead of "#datetime" and adding a new column with the date as a reference to the original table to compare the two columns of dates. Example: "i think you need to add hours, minutes, seconds to the datetime. So try #datetime(2020,09,01,0,0,0)" While these discussions provided various recommendations and suggestions for handling dates and datetimes in APIs and programming languages, there wasn't a clear consensus on the best practice. The recommendations above can serve as a starting point, but individual use cases and requirements may dictate which approach works best for a specific situation.

Jump to top

Research

"Rest API Model Versioning and Deployment Best Practices with Blueprints"

  • The post in the subreddit r/flask discusses the subject of versioning and deployment of a REST API using MethodViews and Marshmallow.
  • The original poster is asking for best practices, strategies, or approaches on versioning models in an API.
  • The post considers different methods of handling versioning, including using Blueprints and URL prefixes, versions in the Request Parsing, Content Headers, etc.
  • The post also raises questions regarding the versioning of models. For instance, whether to implement a versioning scheme for table names (e.g., app_v1_modelname) and how to handle models within a Continuous Integration strategy.
  • One of the comments suggests that the only reason to version database tables or an API is if there is a breaking change, and that new functionality that doesn’t change the behavior of existing functionality could be implemented without creating a new blueprint.
  • The same comment recommends using the Flask-migrations framework to update database models and avoid making breaking changes.
  • Another comment mentions using GraphQL to address some of the versioning concerns.
  • The overall recommendation in the post is to use Blueprints and URL prefixes to handle API versioning, and Flask-Migrate and Alembic scripts for versioning database models.
  • Some users suggest using Swagger, RESTful API Modeling Language (RAML), or OpenAPI Specification (formerly known as Swagger Specification) for documenting and describing APIs.
  • One user recommends using application/json as the Content-Type of POST requests and returning time values as ISO formatted strings.
  • Another user suggests using the ISO format, particularly UTC time, as the universal data exchange format for dates and times in APIs.
  • The potential issues with using local time zones are also discussed.
  • One user mentions using Python’s built-in datetime module for handling dates and times in the API.
  • Overall, the webpage provides some insights into versioning and deployment of REST APIs but does not directly address the best practices for accepting dates and times in an API.

"Proposed guide for date and time handling in Python"

  • The webpage is a guide for handling date and time in Python by a Reddit user.
  • The post suggests a set of rules for handling dates within Python applications, which include:
    • Avoiding calling datetime.datetime.now() without timezone.
    • Avoiding .astimezone() on a naive datetime.
    • Always creating timezone-aware datetimes.
    • Carrying aware datetimes in UTC everywhere and printing them to user timezone on output if possible.
    • Not carrying around any naive datetimes.
    • Assuming naive datetimes are in UTC.
    • Always adding/subtracting datetimes in UTC to avoid time offsets due to DST.
    • Using tz.normalize(dt) if adding/subtracting in non-UTC is necessary.
  • The post gives some unannotated tips on datetime operations in Python, including modules to import, an example of setting the current datetime of a user in their timezone, and handling of naive datetimes.
  • The post also provides annotated cookbook tips for using Pytz, including how to get current UTC time as a timezone-aware datetime, how to convert an aware datetime to a named timezone, how to add timezone to a naive datetime using a Pytz timezone object, and how to print a datetime with timezone.
  • The post includes instructions on using different methods for parsing dates, including date parsing with Dateutil, timezone parsing via Pytz, parsing from a string such as “tomorrow,” and parsing ISO format date strings.
  • The post instructs not to use datetime.datetime.fromisoformat(s) as it does not recognize “Z” as UTC.
  • The post includes a comment from another Reddit user with a two-stage timezone selector dictionary, using Pytz.common_timezones for user selection.
  • The post contains other useful comments from Reddit users, including:
    • A recommendation for a subclass of datetime to evaluate datetime representations in a project.
    • Suggestions to implement large methods as class methods.
  • The post is from two years ago and has 14 points.

"How does one sort by date in a Dataframe?"

  • The discussion revolves around sorting and converting date and time values in DataFrames in Julia.
  • The user is trying to sort a DataFrame by two fields, VectorID and DateField, which contains dates in a Date format.
  • The issue with the user’s approach is that January, February, and other months are all lumped together when sorting.
  • The reason for this is that the DateField is being read in as a String.
  • To sort the values chronologically, the user has to convert the format of the DateField from a string to a date format.
  • One solution proposed by a Reddit user is to convert the dates when importing the file so that they meet the desired format right from the start. Specifically, one can use the CSV.read function, setting the date format to a custom value.
  • Another solution is to convert the date format after importing it. To convert the DateField column from String to Date format, one can use DateTime().(df.B, “YYYY-uuu-dd”).
  • To sort the DataFrame, an example given is to use sort!(df, (:B)), where df is the DataFrame and :B is the column name containing the dates.
  • One solution proposed in the discussion involves utilizing the Dates package and creating a new date format.
  • By using Array{date} and specifying a DateFormat, one can read specific elements of the string into an array of Dates.
  • Then, the dates can be assigned to DateFields in the DataFrame using a for loop, to be specific.
  • One thing to note when assigning the new dates to the DataFrame is that DateFields need to be replaced entirely, not modified, or the program will generate an error.
  • The discussion highlights that reading data in as a custom date format can be helpful in ensuring that data is correctly sorted to avoid any strange or unexpected results.
  • One user points out that developers must pay attention to how the query is constructed. This is because the date format used in the query inevitably affects the way the results are returned.
  • Another user recommends building in safety mechanisms, such as a snapshot of the state of the database at a given time, to avoid data loss or corruption issues.
  • Additionally, users highlight the potential issues that can arise from working with dates and time zones and recommend storing dates and times in an easily adjustable format to avoid difficulties.
  • Users also recommend conducting thorough testing of any date-conversion code, such as by running tests for leap years and other corner cases.

"Handling timezones and dates in Python"

  • A post on Reddit from 7 years ago discusses the use of different libraries to handle timezones and dates in Python.
  • The initial question is asking if there is a library or combination of libraries that can handle all date-related tasks.
  • Arrow and Delorean are consistently recommended libraries in the responses.
  • One user suggests that Pandas, a library for data manipulation, has all the necessary functionality for handling dates.
  • The post includes discussions on the complications of dealing with timezones, with users expressing different opinions on how best to handle them.
  • One user suggests that using naive datetimes and keeping track of timezones manually can be simpler, while another argues that timezone-aware datetimes can be compared regardless of the timezones they are in.
  • Users share various personal experiences and preferences with different libraries, with some pointing out that none of the available libraries are perfect.
  • One user suggests that it would be beneficial to port joda time to pure Python.
  • Another user suggests that the complexity of timezones makes it hard to create a simple and predictable library for managing dates effectively.
  • Personal anecdotes about specific libraries are shared, with comments on their perceived flaws and strengths.
  • One user describes their frustrations with the other options and explains why they created their own library for handling dates.
  • One user suggests including time.time() in log files as an easy way to track time, and another suggests using Hungarian notation to distinguish between local and UTC times.
  • A video link is shared for entertainment purposes.
  • The post includes discussions of line length in code and the difficulties of reading long lines in GitHub’s viewer.
  • Two users share specific GitHub repositories where they have contributed to code for handling dates.
  • One user warns against using Arrow, saying that it is fundamentally broken.

"Which backend language would you choose for a REST API?"

-Relevant: True -Importance: 4

Notes:

-This page is a Reddit thread from 4 years ago discussing backend languages for building a REST API.

-Several users mentioned using specific backend languages like Go, PHP, Node.js, Ruby on Rails, Kotlin, and Elixir for building an API for their CRUD application.

-One user mentioned using JavaScript because it’s a weakly typed language and has the ability to define flexible interfaces.

-They discussed the importance of choosing a language that the developer is comfortable with and not to choose a language based on performance benchmarks.

-Some users discussed the shortcomings of Node.js for CPU-heavy operations and the speed advantage of Golang, but most users mentioned that the language doesn’t really matter for CRUD APIs.

-DB performance discussions were also brought up, and a user mentioned that network latency, and processing contribute to the amount of time the DB adds to API servers.

-The performance of the language used is insignificant for DB performance, but mature and performant languages like C++ are common for developing databases because they outperform Golang.

-One user mentioned using Go if they need higher concurrency or if there is more processing involved because Go’s handling of concurrency is beautiful.

-Some users mentioned specific combinations of languages and frameworks to use like Kotlin and Vert.x combo, and Node.js or Elixir for websockets, and Go for spinning up and spinning down servers to handle millions of requests a minute.

-One user discussed how different backends commonly implement REST APIs; developers should instead wonder why people choose different backend languages in the first place. This user also recommended developers use Node if they already know JavaScript.

-Another user wrote “It’s not what you use, it’s what you know,” and recommended using a backend language that the developer is already familiar with.

-Performance of the language only matters when developers reach the scale of needing 1000 or more different machines to handle requests.

"[deleted by user]"

Not used in article

"Comparing dates in Power Query"

  • The webpage is a Reddit post in the r/PowerBI community, originally posted two years ago.
  • The post, with 12 upvotes, is titled “Comparing dates in Power Query.”
  • A user had a question on how to compare a date column to a static date value in Power Query. They wanted to see if their date field was greater than or equal to September 1st, 2020, and were trying to write this in a custom column.
  • They tried “if [date] >= #datetime(2020,09,01) then ‘Y’ else ‘N’,” but it didn’t work.
  • Another user chimed in, suggesting that the datetime value needed hours, minutes, and seconds added to it, so they tried “#datetime(2020,09,01,0,0,0)” instead, which worked for the original poster. That recommendation had six upvotes.
  • Other users suggested different solutions or techniques:
    • Another person recommended using “#date(2020,09,01)” instead of “#datetime,” and suggested adding a new column with the date as a reference to the original table to then compare the two columns of dates. That suggestion had three upvotes.
    • Someone else suggested hard-coding September 1st, 2020, as a new column and then comparing the two dates in each row using a custom column, but clarified that this wasn’t a Power Query solution, but a DAX solution. This suggestion had one upvote.
  • There was also a brief thread about how this could be done with two tables with a list of dates in each, with some users recommending compared every date in the first table against every date in the second table, while others suggested creating a calculated column comparing the two tables if a relationship was established between them.

"Using Date Filter on Graph API query"

  • The webpage is on Reddit and discusses using a date filter on Graph API query to retrieve information about messages and service health.
  • The OP was able to retrieve the correct information using Graph Explore and a GET request URL.
  • Using the command “Invoke-MgGraphRequest -Uri” on PowerShell, the script was not able to apply the filter in the query correctly.
  • Several users commented on the post to suggest solutions to the problem the OP was facing.
  • One user suggested using the script below to retrieve messages or issues from the last day: $DaysRange = (Get-Date).AddDays(-1); $DaysRangeZ = Get-Date($DaysRange) -format s; $Uri = "https://graph.microsoft.com/v1.0/admin/serviceAnnouncement/issues?$filter=lastModifiedDateTime ge $DaysRangeZ” + “Z”; $Invoke = Invoke-MgGraphRequest -Uri $Uri -Headers $token -Method Get -Verbose. - Another user suggested using single quotes and two single quotes around the date instead of double quotes. - Some users suggested using$filter=lastModifiedDateTime gt ‘2022-01-15’instead of$filter=lastModifiedDateTime ge 2022-01-15T14:41:09Z` as it worked for them. - A user also mentioned that Graph API queries do not use the “-“ in the comparison operators. - Another user was unable to retrieve messages from the day before despite using the suggested solutions. - However, the thread did not provide a best practice way to accept dates and datetimes in an API.

💭  Looking into

The article gives tips on how to make the API user-friendly

💭  Looking into

The article provides security recommendations and best practices

💭  Looking into

The article explains the various methods of accepting dates and datetimes and their pros/cons