Currency selection in an API

[Steve Marshall]

Hi all,

I’m writing some specs for an API, and was wondering if anyone’s got any thoughts on the use of HTTP headers for currency selection?

I’m currently erring toward `Accept-Currency` (behaving akin to the other HTTP Accept headers, but with ISO 4217 currency codes) on the request, and `Content-Currency` on the response. Can anyone see any issues with this? Is this HTTPish, or not?

Per Mark Nottingham <http://www.mnot.net/blog/2012/07/11/header_versioning#comment-1805>:

Creating new negotiation mechanisms when they're not needed just makes HTTP more complex, more error-prone […], and less likely to interoperate with other software (how do you do this with a browser if you don't want to XHR everything)?

So: am I introducing an unnecessary content negotiation mechanism, or does this seem like an apt use of headers? If using a header for this is wrong, what’s the best way to do it? A currency querystring param and listing the currency with each currency amount?

[Paul Russell]

Interesting question!

I think you need to be very careful here about in what context you're talking about currency. Effectively, without the currency, your amount attributes are more or less meaningless.

It feels to me like those currencies should therefore belong as first class attributes in the representation itself, so that there is no ambiguity, and no intellectual burden on the caller to /remember/ that there is a header in the response with a currency in it. Without that, I think you'll hit situations where your consumers will /assume/ the currency is their own, which could be bad news indeed!

If you buy the above however, you could still use accept header to negotiate which currency is returned in that representation. 

I think depending on your use case, you still need to be a little careful with that. Exchange rates fluctuate, and sometimes it makes sense to use an exchange rate for /today/, but sometime it makes sense to use a rate from e.g. the transaction date. By just wrapping it all up in that one header and blindly converting everything at today's rate, you could end up violating user's expectations of your API returning stable, predictable results.

I think there /are/ circumstances where the dynamic currency selection approach probably works - e.g. An API that is providing MI or analysis of data, so I wouldn't rule it out completely without knowing your use case.

Hope that helps,

Paul

—
Sent from Mailbox for iPhone

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Toralf Richter]

Hi,
my gut feeling would be to keepeverything that is an application concern (as currency selection could be) out of the HTTP protocol level. HTTP is to me more transport than means of choice to express a complete set of functional aspects and concerns that you will need eventually to build a (suffiently rich + complex) API.
In other words (I am not a RESTafarian) it is OK to express certain functional aspects of your API with what HTTP has out of the box (GET, PUT, DELETE) but if you go beyond simple CRUD operations you'll notice that the approach is limited and you start tweaking and twisting HTTP to still get it working for you (as you try now) - which I don't think is the right way.

Ofcourse these are just my personal views ...

B/R, Toralf

[Jeff Smith]

One example you may want to look at is the GSMA OneAPI Payment APi
http://www.gsma.com/oneapi/payment-restful-netapi

[Rahul Dighe]

My preference would be for it to be not part of the HTTP headers - I think having it part of your request / response would probably be more readable + I think having it part of the headers just intuitively feels unnecessarily complex. 

[Steve Marshall]

Thanks for all the opinions, gang!

I’ve opted to drop the headers and use `?currency` and a `currency` attribute alongside values, per everyone’s suggestions of keeping application-level things out of HTTP headers and such.

The more complete context is that this is a pretty typical shopping API: list products, get product details, buy products, and I think keeping things as simple as possible is probably for the best.

Ta!