ISO8601 specifies Gregorian calendar only. Past that, determining the local timezone is the UX’s responsibility. This can be quite complicated in mobile scenarios, so the API should stick to UTC in the response. See my article 5 Laws of API Dates and Times for more info.

1) ISO 4217 only holds information about the currency code (alpha & numeric) and number of decimals. For the rest, it’s really wrong to say the code “helps to dictate” but “helps to make fragile assumptions” – e.g. EUR isn’t to be appended to the amount, just because it’s EUR; in English, Latvian and other locales, it’s supposed to be prepended. Point is: use locale to determine things currency format settings. As an American (en-us), you want the code/symbol to be prepended USD 12, $12, even if we’re not talking USD – €12. Same goes for formatting an amount – thousand symbol (dot, comma, space, nothing), decimal symbol (comma, dot)

2) I might be in the wrong here, but I see no reason why one would make the distinction between language and locale in terms of the Accept-Language header. If the API is localized (though IMO it’s the client that should care about localization), then Accept-Language: it-it should output localized content (not just take care of translation, while leaving out the format of 12$ as is).

3) Before one dives into using X-Currency, one has to ask a few questions
– is my product/service/whatever offered in more than a handful of currencies? If not, then consider just dumping all prices and all available currencies. e.g. instead of {price:10, currency:”EUR”}, output {prices: [{amount:10, currency:”EUR”}, {amount:20, currency:”USD”}]
– I use more than a handful of currencies, but am I in the business of currency conversion? Most probably not, because your prices are biased towards marketing and other factors, and thus you fix your prices manually – you don’t just say I want to make 100 EUR on this product, and then people pay the equivalent in their currency. If you are certain of it, build up or recommend a 3rd party currency-conversion service endpoint. This way, your regular output is still in 1..5 major currencies; if another currency is desired, the client can use the service endpoint to convert prices.

Thanks

In write-capable scenarios, I would recommend some additional internal systems design. Namely ensuring that users have a currency preference set in their account preferences, and only allow updates in that currency. In scenarios where they have no ‘account’ (unlikely with money involved, but possible in financial industries), the X-Currency header can be utilized as a non-negotiated request header, specifying the currency in the POST/PUT data.

Typically I think of prices and other money values as fixed in a specific currency, but they can also be displayed approximately in other currencies for localization. This article doesn’t touch on a write-capable API. Would you accept a client-side request for a specific currency (eg. X-Currency header) and actually affect something material, like the charge for an ecommerce purchase?

@mfenniak