For the Amadeus self-service rest APIs: v1/shopping/flight-offers and flight-dates, is the price.total response field inclusive of all taxes and fees?
I seem to need to add total + totalTaxes to get a price that's close to the one provided by the airline directly.
If there are developer docs that explain in more detail each response field, please do point me to them. I have been unable to find any.
In reference to these APIs:
https://developers.amadeus.com/self-service/category/203/api-doc/4/api-docs-and-example/10002
https://developers.amadeus.com/self-service/category/203/api-doc/5/api-docs-and-example/10003
and this field:
"price": {
"total": "259.91",
"totalTaxes": "185.91"
},
“total” is the total price you will have to pay, it includes the totalTaxes.
You can access the model directly on Swagger (under the Response Class (Status 200)) you have the Model button. But you are right the description of those parameters need to be added, point taken.
As highlighted in the accepted answer, the total price is the total including all taxes, personally, I was also initially confused and had to manually check with a travel agent to confirm. I would suggest Amadeus splits the description as follows
"price": {
"totalFare": "74.00",
"totalTaxes": "185.91"
"totalAmount": "259.91"
},
Related
For example, if there is a rest api for a shop system to add articles to my shopping cart without knowing the id, what would be the most restful way to design the url to call and what about the serverside implementation? I know there is some flexibility when designing rest apis, but what is "state of the art"?
Lets say my database does have the table "articles", "shoppingcarts", "article_pos".
articles (id, article_name, price, color),
shoppingcarts (id, description),
article_pos (id, shoppingcart_id, article_id)
Example to create an article:
POST "/api/shop/article/"
Request:
{
"article_name": "table",
"price": "100.00",
"color": "brown"
}
Example to get an existing article:
GET "/api/shop/article/4711"
Response:
{
"id": "4711",
"article_name": "table",
"price": "100.00",
"color": "brown"
}
But how I should design the url if I want to add article "4711" to the shopping cart?
Like this?
POST "/api/shop/shoppingcart/addArticle/4711?amount=1"
or Like this?
POST "/api/shop/article_pos/"
Request:
{
"shoppingcart_id": "1",
"article_id": "4711"
}
And how to get the article ID if a client doesn't know the ID (4711) but the articlename (table)?
But how I should design the url if I want to add article "4711" to the shopping cart?
POST /api/shop/shoppingcart/addArticleById/{4711}
fetch article details from article table, get the amount.
update shopping cart with these details
how to get article ID if a client doesn't know the ID (4711) but the articlename (table)?
POST /api/shop/shoppingcart/addArticleByName/{table}
fetch article details from article table, get the amount.
update shopping cart with these details
State Of the Art:
indentify resource by ID only, and use it for creating, updating details.
REST -> deals with resource first, hence a resource is first class citizen identified by a Id.
I already have a working FedEx API in production with two services: rate and shipping.
Note that I use:
My own packages: "PackagingType": "YOUR_PACKAGING"
Almost always I know estimated weight of parcel: "RequestedPackageLineItems": { "Weight": { "Value": "42" } }
So, I do rate&buy label with concrete price. But sometimes package exceeds dimensions or weight is changed after buying label – this leads to additional payments and total price for label is different in real life than i receive at the moment of buying label.
The question is: How can I get REAL weight and price of sent package?
I tried to use tracking service with no luck – API returns old incorrect data of weight and no price.
For example, I know that label 123456789012 was created with 2 lbs of weight with price 9.45$. Later on, weight changed dramatically (to 48 lbs) and price changed to 48.98$. I know that because of talking with real people but request to tracking service of FedEx API says that PackageWeight is still 2 LB and Payments parameter contains only "Type": "SHIPPER_ACCOUNT" value and that's all.
Okay, I've found out that i need to request invoices because they contain needed information. How to get them? Didn't find any documentation inside PDF for developers.
Let's say that I'm developing an application about shopping. I have defined the following endpoints, which are quite self-explanatory:
GET /items
GET /items/{item-id}
GET /stores
GET /stores/{store-id}
Now, I want to create another endpoint that displays the price of individual item at different stores. This price information is not included in /items/{item-id} since I don't think it's suitable to be an attribute of item, and getting the list of prices requires a bit more calculation as I cannot return the object directly. I will name the endpoint /items/{item-id}/prices and expect a response like this:
[
{
"store_id": "store_1",
"price": 13.00
},
{
"store_id": "store_2",
"price": 12.99
}
]
I want to extend this further and create another endpoint that returns the price information for all items, but I'm having trouble naming this endpoint. So far I've thought of /items/prices or /items?display=prices but the former might be confusing as it matches with /items/{item-id}, and the latter just.. does not seem to make sense for me.
What is the best name to pick for my endpoint so that it stays consistent with the convention?
For all items pricelist endpoint for a single store, I'd recommend GET /stores/{store-id}/prices or GET /stores/{store-id}/pricelist.
For all items/stores pricelist, I'd use GET /items/pricelist or GET /items/*/pricelist, (both special before /items/{item-id}), which could be store-specified on demand by ?store={store-id}.
Adding prices endpoint to items would make no sense as item itself has nothing to do. It is store's responsibility to dictate the price.
I would suggest renaming stores endpoint to /stores/description/{id} and adding prices subcategory /stores/prices/by-item/{id} and /stores/prices/by-store/{id}.
I would say that for sepecfic item /prices/{store-id}/{item-id}
and for all prices /prices/{store-id}
I originally reported this to Self-Service support in December, but I never got a response. I recently realized that, even in the production environment, selecting a currency parameter for an Inspiration or Cheapest-Date endpoint always returns the origin country's currency despite selecting another currency. (In the Low-Fare endpoint it seems to work as designed.) I tested this in both my web application and in Amadeus' own explorer tool. Here is a snip from the JSON response in the Explorer:
"meta": {
"currency": "EUR",
"links": {
"self": "https://test.api.amadeus.com/v1/shopping/flight-dates?origin=MAD&destination=MUC&departureDate=2019-04-14,2019-10-10&oneWay=false&duration=4,7&nonStop=true¤cy=USD&viewBy=DATE"
},
"defaults": {
"departureDate": "2019-04-14,2019-10-10"
}
}
Notice that the meta.currency value is EUR, but the meta.links.self (the query I ran) shows a GET parameter of currency=USD. The same problem I reported in Dec.
I am posting this for suggestions about how to get some action from Amadeus (hope they read this), or a suggested workaround (obvious one is hiding Currency field from the Inspiration and Cheapest-Date form).
The currency parameter in Flight Inspiration and Cheapest Date Search, works only along with maxPrice. Prices in the response are computed in a currency determined by the origin/destination pair: they cannot be converted in a given currency.
Since it's a bit confusing, we are going to update the currency parameter naming and documentation. Point taken and sorry for the delay in the response.
We are developing a RESTful api that accepts query parameters in the request in the form of JSON encoded data.
We were wondering what is the correct behaviour when non requested/not expected parameters are passed along with the required ones.
For example, we may require that a PUT request on a given endpoint have to provide exactly two values respectively for the keys name and surname:
{
"name": "Jeff",
"surname": "Atwood"
}
What if a spurious key is passed too, like color in the example below?
{
"name": "Jeff",
"surname": "Atwood",
"color": "red"
}
The value for color is not expected, neither documented.
Should we ignore it or reject the request with a BAD_REQUEST 400 status error?
We can assert that the request is bad because it doesn't conform to the documentation. And probably the API user should be warned about it (She passed the value, she'll expects something for that.)
But we can assert too that the request can be accepted because, as the required parameters are all provided, it can be fulfilled.
Having used RESTful APIs from numerous vendors over the years, let me give you a "users" perspective.
A lot of times documentation is simply bad or out of date. Maybe a parameter name changed, maybe you enforce exact casing on the property names, maybe you have used the wrong font in your documentation and have an I which looks exactly like an l - yes, those are different letters.
Do not ignore it. Instead, send an error message back stating the property name with an easy to understand message. For example "Unknown property name: color".
This one little thing will go a long ways towards limiting support requests around consumption of your API.
If you simply ignore the parameters then a dev might think that valid values are being passed in while cussing your API because obviously the API is not working right.
If you throw a generic error message then you'll have dev's pulling their hair out trying to figure out what's going on and flooding your forum, this site or your phone will calls asking why your servers don't work. (I recently went through this problem with a vendor that just didn't understand that a 404 message was not a valid response to an incorrect parameter and that the documentation should reflect the actual parameter names used...)
Now, by the same token I would expect you to also give a good error message when a required parameter is missing. For example "Required property: Name is missing".
Essentially you want to be as helpful as possible so the consumers of your API can be as self sufficient as possible. As you can tell I wholeheartedly disagree with a "gracious" vs "stern" breakdown. The more "gracious" you are, the more likely the consumers of your API are going to run into issues where they think they are doing the right thing but are getting unexpected behaviors out of your API. You can't think of all possible ways people are going to screw up so enforcing a strict adherence with relevant error messages will help out tremendously.
If you do an API design you can follow two path: "stern" or "gracious".
Stern means: If you do anything I didn't expect I will be mad at you.
Gracious means: If I know what you want and can fulfil it I will do it.
REST allows for a wonderful gracious API design and I would try to follow this path as long as possible and expect the same of my clients. If my API evolves I might have to add additional parameters in my responses that are only relevant for specific clients. If my clients are gracious to me they will be able to handle this.
Having said that I want to add that there is a place for stern API design. If you are designing in an sensitive domain (e.g. cash transactions) and you don't want to leave room for any misunderstanding between the client and server. Imagine the following POST request (valid for your /account/{no}/transaction/ API):
{ amount: "-100", currency : "USD" }
What would you do with the following (invalid API request)?
{ amount: "100", currency : "USD", type : "withdrawal" }
If you just ignore the "type" attribute, you will deposit 100 USD instead of withdrawing them. In such a domain I would follow a stern approach and show no grace whatsoever.
Be gracious if you can, be stern if you must.
Update:
I totally agree with #Chris Lively's answer that the user should be informed. I disagree that it should always be an error case even the message is non-ambiguous for the referenced resource. Doing it otherwise will hinder reuse of resource representations and require repackaging of semantically identical information.
It depends on your documentation.. how strict you want to be .. But commonly speaking, Just ignore it. Most other servers also ignore request parameters it didn't understand.
Example taken from my previous post
Extra Query parameters in the REST API Url
"""Google ignore my two extra parameters here https://www.google.com/#q=search+for+something&invalid=param&more=stuff"""
Imagine I have the following JSON schema:
{
"frequency": "YEARLY",
"date": 23,
"month": "MAY",
}
The frequency attribute accepts "WEEKLY", "MONTHLY" and "YEARLY" value.
The expected payload for "WEEKLY" frequency value is:
{
"frequency": "WEEKLY",
"day": "MONDAY",
}
And the expected payload for "MONTHLY" frequency value is:
{
"frequency": "MONTHLY",
"date": 23,
}
Give the above JSON schema, typically I will have need a POJO containing frequency, day, date, and month fields for deserialization.
If the received payload is:
{
"frequency": "MONTHLY",
"day": "MONDAY",
"date": 23,
"year": 2018
}
I will throw an error on "day" attribute because I will never know the intention of the sender:
frequency: "WEEKLY" and day: "MONDAY" (incorrect frequency value entered), or
frequency: "MONTHLY" and date: 23
For the "year" attribute, I don't really have choice.
Even if I wish to throw an error for that attribute, I may not be able to.
It's ignored by the JSON serialization/deserialization library as my POJO has no such attribute. And this is the behavior of GSON and it makes sense given the design decision.
Navigating the Json tree or the target Type Tree while deserializing
When you are deserializing a Json string into an object of desired type, you can either navigate the tree of the input, or the type tree of the desired type. Gson uses the latter approach of navigating the type of the target object. This keeps you in tight control of instantiating only the type of objects that you are expecting (essentially validating the input against the expected "schema"). By doing this, you also ignore any extra fields that the Json input has but were not expected.
As part of Gson, we wrote a general purpose ObjectNavigator that can take any object and navigate through its fields calling a visitor of your choice.
Extracted from GSON Design Document
Just ignore them.
Do not give the user any chance to reverse engineer your RESTful API through your error messages.
Give the developers the neatest, clearest, most comprehensive documentation and parse only parameters your API need and support.
I will suggest that you ignore the extra parameters. Reusing API is a game changer in the integration world. What if the same API can be used by other integration but with slightly extra parameters?
Application A expecting:
{
"name": "Jeff",
"surname": "Atwood"
}
Application B expecting:
{
"name": "Jeff",
"surname": "Atwood",
"color": "red"
}
Simple get application application A to ignore "color" will do the job rather to have 2 different API to handle that.