I have a question about a simple REST API endpoint.
The endpoint can accept a value expressed in EURO then returns the corresponding value in DOLLAR, conversely it can accept a value in DOLLAR an return the value in EURO.
I would like to know how I should name this endpoint to respect REST API endpoint naming conventions and best practices.
So far, I have thought about:
-convert-euro-dollar (Probably bad because it uses a verb)
-euro-dollar (Good option?)
Thanks in advance!
I would like to know how I should name this endpoint to respect REST API endpoint naming conventions and best practices.
REST doesn't care what naming conventions you use for your resource identifiers. (Hint: URL shorteners work.)
See Tilkov 2014.
The motivation for choosing "good" resource identifiers is much the same as the motivation for choosing "good" variable names -- the machines don't care, therefore you have extra degrees of freedom that you can use to make things easy for some people.
Possible people you might want to make things easy for: folks looking at resource identifiers in their browser history, operators looking at identifiers in HTTP access logs, writers trying to document the API, etc.
https://www.merriam-webster.com/dictionary/put
Verbs are fine; notice that this URL works exactly the way that you and your browser expect it to, even though the identifier includes a HTTP method.
As suggested by https://stackoverflow.com/a/48692503/19060474 and https://stackoverflow.com/a/10883810/19060474, I would go with one of
GET /dollar/from-euro
GET /euro/to-dollar
GET /currency/usd/from/usd
GET /currency/eur/to/usd
as long as you stay consistent.
Keep in mind, that you should be able to easily deduce from the endpoint what it will likely do. So you should make clear in which direction the conversion will be performed.
With euro-dollar or convert-euro-dollar this is not clearly expressed because one can not determine if the endpoint expects dollar (which dollar by the way, there are quite some variants like USD, AUD, CAD, ...) and converts to EUR or vice versa.
I also suggest you consider using currency codes from the ISO 4217 standard to avoid ambiguity. You can find some of them at https://www.iban.com/currency-codes.
Be aware that answers to this are opinion based, because there is no REST constraint on URI design. All you need is following the URI standards which tells you that the path is hierarchical and the query is non-hierarchical, and that's all. Even that part is sort of flexible.
As of the URI design conventions, I like to describe the operation first and convert it into a verb and a noun. After that I choose HTTP method for the verb and try to describe the rest of it with a noun and attach that second noun to the first one and convert it to an URI template. So I like to name my resources with nouns.
The endpoint can accept a value expressed in EURO then returns the corresponding value in DOLLAR, conversely it can accept a value in DOLLAR an return the value in EURO.
Here the operation name would be convertEuroToDollarOrDollarToEuro. I think either we have two operations here convertEuroToDollar and convertDollarToEuro or we need a more general operation name something like convertCurrency and restrict it to the supported currencies, which are Euro and Dollar. Here either I would use POST /conversion to create a new conversion or I would use GET /conversion to read the conversion result.
POST /currency/conversion {"fromCurrency": "EUR", "toCurrency": "USD", "amount": 100}
POST /currency/conversion {"fromCurrency": "USD", "toCurrency": "EUR", "amount": 100}
GET /conversion/{amount}/{fromCurrency}/to/{toCurrency}
GET /conversion/100/EUR/to/USD
GET /conversion/100/USD/to/EUR
GET /currency/conversion?from={fromCurrency}&to={toCurrency}&amount={amount}
GET /currency/conversion?from=EUR&to=USD&amount=100
GET /currency/conversion?from=USD&to=EUR&amount=100
If your service meets the HATEOAS constraint, then this kind of URI structure matters only from service developer perspective, because it is relative easy to figure out the HTTP methods URI templates for the endpoints and bind them to controller methods.
From service consumer or REST client perspective what matters here is the operation name, which is convertCurrency and its parameters: fromCurrency, toCurrency, amount. You need to add these to the documentation and if you can with your actual MIME type attach the metadata to the hyperlink, which represent this operation. So at least do something like:
{
method: "GET",
uri: "/conversion/{amount}/{fromCurrency}/to/{toCurrency}",
type: "convertCurrency"
}
A more advanced solutions would describe the documentation of the convertCurrency operation in a machine readable way. For example Hydra does this: https://www.hydra-cg.com/ and maybe HAL forms can be another solution: https://rwcbook.github.io/hal-forms/ .
