There's probably no right answer Booth but here's what I would consider.
Firstly, your temperature conversion resource is clearly a functional resource, not a "thing", so it's not a customer or an item or something that you can do CRUD operations on, rather a function that you can call to perform a calculation. As it is, it's of limit complexity and has limited scope for additional complexity so there's probably nothing wrong with leaving it as it is, which I assume is like this:
/coop/f2c/90
but it could equally well be
/coop/f2c?temp=90
However, what if your function were to require more parameters? If they were just concerned with formatting for example then it would be okay to add them like this:
/coop/f2c/90?precision=2
/coop/f2c?temp=90&precision=2
but if the function were more complex and required more parameters to work then I probably would not use URL path parameters. Take for example a function to validate a credit card, that might require the card holder's name, postcode, card number and expiry date. Trying to fit that lot into a URL would be wrong IMO because the URL implies a hierarchy and there is no hierarchy here, just a bunch of inputs; "/validate-card/A%20Person/1234432112344321/0322/65183" makes no sense. In this case I would either use a GET and query parameters:
/validate-card?cardholder=A%20Person&card-number=1234432112344321&expires=0322&postcode=65183.
or a POST to the URL "/validate-card" with a JSON body:
{
"cardholder": "A Person",
"card-number": 1234432112344321,
"expires": "0322",
"postcode": "65183"
}
I don't think it makes much difference which although semantically the GET feels better maybe because you're simply asking for something, but remember also that there's limited space in the URL, so if your function were sending an e-mail which might require a large amount of body text it would most likely been done with POST and a request body, and in this case POST feels more right because you are requesting that something be done by the server.
On the other hand, if your resource was a thing, like a customer then I would probably arrange my URLs something like this:
GET /customers?page=1&filter=smith ----> get the first page of a list of customers filtered by "smith"
GET /customers/1 ----> get customer 1
GET /customers/1/addresses ----> get a list of addresses associated with customer 1
GET /customers/1/addresses/1 ----> get address 1 from customer 1
Here's there is a clear hierarchy so it makes sense that the URLs reflect this, also you can use the other HTTP verbs like this for example:
/customers
GET ----> get a list of customers
POST {"name": "New Customer"....} ----> Create a new customer using the information provided on the request body
/customers/1 ----> get customer 1
GET ----> get customer 1
PUT {"name": "New name"....} ----> Modify the customer using the information provided on the request body
DELETE ----> Delete the customer
/customers/1/addresses
GET ----> get a list of addresses associated with customer 1
POST {"address-type": "BILL"....} ----> Add a new address to the customer using the information provided in the request body.
/customers/1/addresses/1
GET ----> get address 1 from customer 1
PUT {"postcode": "New name"....} ----> Modify the customer address using the information provided on the request body
DELETE ----> Delete the customer address
etc. etc.
There are plenty of good RESTful APIs to have a look at (like Twitter for example) and loads of resources, but I found "The RESTful Webservices Cookbook" by Sabbu Allamaraju one of the most useful, the only downside is that it uses an old fashioned protocol called Atom much of the time in the examples, but the basic concepts are well explained I think.
Tim.
________________________________
From: WEB400 <web400-bounces@xxxxxxxxxxxxxxxxxx> on behalf of Booth Martin <booth@xxxxxxxxxxxx>
Sent: 14 January 2019 23:31
To: Web Enabling the IBM i (AS/400 and iSeries)
Subject: Re: [WEB400] Using REST service created with IWS
Walk me through this. The temperature conversion example included with
IWS... The address is
https://eur03.safelinks.protection.outlook.com/?url=http%3A%2F%2Fan.iSeries.com%2Fcoop%2F&data=02%7C01%7C%7C8c177674f11a48fb038208d67a7019e2%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636831019228742635&sdata=pmjqzKh2n%2BIGbm%2FKVlvS5PQLN2x7eiXQUvUag0ZSjk0%3D&reserved=0 I want to say F2C and
90, meaning I want the api to convert 90 degrees Fahrenheit to
Celsius. What should that look like?
On 1/14/2019 4:16 PM, Tim Fathers wrote:
While I agree the definition of REST can be pretty flexible and there are no hard and fast rules, I think it is a fairly well established rule of thumb that the URL should generally identify the resource, not the query parameters. The body (which I think you mean by "standard input") is where the payload should go, and should not be used on on a GET request in any case.
In some APIs the resource is not a "thing" but a function, in which case it is considered ok to pass query parameters to it in the URL for a GET or in the body for a POST. The example of this from my favourite REST book "The RESTful Webservices Cookbook" is a distance calculator. So /calc_distance?from=wiesbaden&to=frankfurt is ok because "distance" is not a thing but a function.
Tim.
--
This is the Web Enabling the IBM i (AS/400 and iSeries) (WEB400) mailing list
To post a message email: WEB400@xxxxxxxxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit:
https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.midrange.com%2Fmailman%2Flistinfo%2Fweb400&data=02%7C01%7C%7C8c177674f11a48fb038208d67a7019e2%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636831019228742635&sdata=4VL2ACUbJlzg3%2FMpOppxZD4J10zRZ9TWNQcamEDPr9g%3D&reserved=0
or email: WEB400-request@xxxxxxxxxxxxxxxxxx
Before posting, please take a moment to review the archives
at
https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Farchive.midrange.com%2Fweb400&data=02%7C01%7C%7C8c177674f11a48fb038208d67a7019e2%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636831019228742635&sdata=yU3m9FrGFNsfrPBckQxPwMCPO%2Fh3kzLGD16WSIjgoHI%3D&reserved=0.
midrange.com
