5 ms·

Most of these best practices forget the hard parts of JSON/REST APIs: - How to handle date and time incl. time zones - JSON has no data type for that - Handlin

• ehutch79 6y ago
  Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.
  • crescentfresh 6y ago
    > Send ISO date/time in utc what's an ISO date/time?
    • deleted 6y ago
      [deleted]
    • lyjackal 6y ago
      I assume GP means ISO8601 Date Time https://en.wikipedia.org/wiki/ISO_8601 https://en.wikipedia.org/wiki/ISO_8601. Default behavior of javascript date json serialization > JSON.stringify(new Date()) '"2021-02-22T20:34:53.686Z"'
      • tshaddox 6y ago
        Then why add the "in UTC" part? ISO 8601 specifies how to designate the time zone.
        • uranusjr 6y ago
          ISO 8601 does not contain timezone information, but offset. Timezone info needs to be specified separately, likely as IANA names. It is a common misconception to time zones though, and in a way demonstrates why it’s best practice to always use UTC. When sending/receiving a datetime, no timezone info is available; if timezone is needed, send it separately (and keep the time value in UTC) to save misunderstandings for everyone.
          • tshaddox 6y ago
            I'm aware of the distinction between ISO 8601's time zone designators (which are simply UTC offsets) and other much more complex notions of time zones such as the IANA tz database (which identifies time zones with an "Area/Location" string and contains information about each zone such as daylight saving time rules and even the historical changes in such rules). That said, "time zone designator" is the formal name of the UTC offset in ISO 8601, and it's reasonable to refer to it as such whenever the distinction is clear.
    • ehutch79 6y ago
      https://en.wikipedia.org/wiki/ISO_8601 https://en.wikipedia.org/wiki/ISO_8601 https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...
    • jshprentz 6y ago
      https://xkcd.com/1179/ https://xkcd.com/1179/
  • chrisandchris 6y ago
    > Send numbers as string [...] Why? Why not send a number as number (double) and treat it as hostile in the backend? I dislike sending numbers as string because I think the different data types exist for a reason.
    • e12e 6y ago
      One reason could be that it's easy to think that a "number" is sanely typed, while you almost never want a double - not for quantity, not for price, etc. So you're going to cast to some (big) integer anyway...
      • Kwpolska 6y ago
        In languages with reasonable number types (i.e. not JS), the parsers are typically able to produce integers, or even BigDecimal, out of a JSON number, without going through double.
        • e12e 6y ago
          I guess I feel returning error invalid integer for a valid json double is a bit wierd - but I guess it's not technicallyaany worse than "could not parse string as integer. It's more that it is expected that strings hold" other" data, like timestamps, while one might expect a double to hold only (but also any) doubles.
    • ehutch79 6y ago
      I don't care if you like it or not, if your numbers are actually that large, serialize it to a string and back out on your backend. You shouldn't be blindly dumping json to a structure anyways. Either that or use a different serialization method to communicate. No one else seems to be complaining about this issue. If JSON doesn't fit your needs, use something else.
    • deleted 6y ago
      [deleted]
    • tomg 6y ago
  • adolph 6y ago
    >Send ISO date/time in utc. With offset, ok. As UTC alone, it doesn't work if you need to know the local time when something occurred, like medication administration, especially when the things may occur across time changes like DST.
    • rsyring 6y ago
      Do not just track offset. If you have to deal with date/time locally, you must have the timezone. Treat this just like bytes/Unicode: accept local time on the edges of the app, convert immediately to UTC, store/use UTC internally, convert back to local on the edges at display time. Yes, it can get more complicated than this of doing calendar math, but I'm not aware of anything gained by just tracking offset.
      • rileymat2 6y ago
        That does not work in the op’s use case because the op wants to know the local time of the medication administration. The endpoint of the viewer may not be in the same local time. If you go this route you may not care about location beyond this one data point, but have to store another location field each time.
  • fmakunbound 6y ago
    Should we put the error code in the http status code and status line, or in the response body? We’re having a great debate at work and it’s been a blast mapping business logic errors to closest http status code spiritual animal. The Dean of the REST Engineering Directorship has decreed a bit of both, but most of The Unwashed (front end developers) are revolting on this matter insisting it all maps to a red-tinted “Sorry, reboot and try again” toast. In other news we’re suspecting transactions are on horizon. Half the backend team are in denial, the other half are busy trying to figure out the most pleasant place to install decidedly “unRESTy URLs” for them. Somebody already set themselves on fire over PUT/POST for that.
• phtrivier 6y ago
  There's and iso for dates as string with the offset, that's usually fine. Handling Post and Patch differently can at least give a general guideline for "overwriting vs keeping fields on update." The localisation part is trivial if you consider that APIs are to be consumed by machines - much harder, if you assume they're used for GUIs. Error handling is easy to define right, but so tedious to implement.... 1+n can be improved by "guessing" which nested ressources are going to be fetched, and include them "by default." But you're right that those are decisions that need to me made, and can quickly be agonised on without adding much value....
• akavel 6y ago
  As to updates (and other aspects of API design too), I highly recommend taking a look at the solutions proposed at https://aip.dev https://aip.dev - e.g. in case of update, https://aip.dev/134 https://aip.dev/134 - note the use of FieldMask (though there's some slight not-yet-resolved inconsistency observed recently by one user: https://github.com/aip-dev/google.aip.dev/issues/673 https://github.com/aip-dev/google.aip.dev/issues/673)
• jethack 6y ago
  Somewhat important tangent: the JSON number type is not a double. It's just a number of arbitrary size and precision in integer/decimal/E format that can be parsed as whatever the parser finds fitting. This distinction is important because you can't serialize infinities or NaN, and there's no guarantee the JSON number can be accurately represented as a double. JS likes to pretend that JSON number is interchangeable with Number and this can result in some fun situations when your Infinity becomes null I guess the point is that JSON has about as much to do with JS as JavaScript has to do with Java.