Hacker News Reader

Comment by derkoe | Hacker News Reader

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 - Handling of numbers (JSON only has double, which does not fit most cases) - Defined and parseable error responses (rfc 7807 plus extra fields for details) - Localization - do you send translated texts or just error codes? - How to handle updates? Overwrite every field? How to update only some fields for a resource? Optimistic locking? - How to handle 1+n problems for reading? ...

View on HN

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.

> Send ISO date/time in utc

what's an ISO date/time?

I assume GP means ISO8601 Date Time https://en.wikipedia.org/wiki/ISO_8601. Default behavior of javascript date json serialization

  > JSON.stringify(new Date())
  '"2021-02-22T20:34:53.686Z"'

Then why add the "in UTC" part? ISO 8601 specifies how to designate the time zone.

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.

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.

https://en.wikipedia.org/wiki/ISO_8601

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

https://xkcd.com/1179/

> 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.

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...

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.

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.

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.

A bit off-topic but I received an email from a government agency today that pretty printed my ZIP code as "12,345", I'm assuming because they store ZIP as a number. Made me wonder what would happen if I used a full 9 digit ZIP code with a minus sign.

Reminds be of a broadly used industry specific database that packs multi-line addresses in a delimited string with an initial integer which indicates the number of lines. Some addresses were written to the database without the initial integer and were addresses in a city with East/West streets with number names. Addresses like 1425 East 34th St commonly written as 1425 E34 were casted as exponents, so an address with 1.425E37 lines, which was a problem for the ETL-downstream database that attempted to make that many rows for address lines. It caused much confusion and delay for the downstream DBAs.

Many of the numbers we use day to day are more like strings than actual integers, though. What sense does it make to divide by a zip code, or two add two zip codes together for instance?

This. Just because something contains numbers doesn't mean that it's numeric. Times aren't numbers because 6pm * 7am doesn't yield a meaningful result.

Same thing with serial numbers, VIN numbers, building floor numbers, phone numbers, etc. All of those should always be strings, because performing "math" on them wouldn't yield meaningful results.

I work in ecommerce and deal with this issue a TON. I see it in things like GTIN/UPC or tracking numbers.

While I basically agree, there‘s a difference between „always send numbers as string“ and „send something that looks like a number but is actually a string as a string“.

Why should i send a dimension as a string? How am I going to calculate the volume from 3 strings?

> Why should i send a dimension as a string?

You shouldn't because a dimension is a number. Something 4 feet long is twice as long as something 2 feet long.

Many != All

So prices are numbers (if supplied in cents, the smallest unit). There is length/depth/height/weight/... A lot of things are actual numbers. Why supply them as string?

I agree partially with you but think ZIP are a very bad example because a zip itself may also contain letters.

>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.

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.

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.

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.

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....

As to updates (and other aspects of API design too), I highly recommend taking a look at the solutions proposed at https://aip.dev - e.g. in case of update, 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)

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.

Reply on news.ycombinator.com