I want to validate an opinion with you.
I have to design a web service that searches into a database of restaurants affiliated to a discount program in a specific country around a given address.
The REST call to such a webservice will look like http://server/search?country=<countryCode>&language=<languageCode>&address=<address>&zipcode=<zipcode>
The problem is that some countries do not have zipcodes or do not have them in the entire country.
Now, what would you do if the user passes such a parameter for a country that does not have zipcodes, but he/she passes a valid address?
Return 400 Bad request.
Simply igonre the zipcode parameter and return results based on the valid address
Return an error message in a specific format (e.g. JSON) stating that zipcodes are not supported for that country
Some colleagues are also favoring the following option
4. Simply return no results. And state in the documentation that the zipcode parameter is not supported. Also we have to create a webservice method which returns what fields should be displayed in the user interface.
What option do you think is best and why?
Thanks!
Well the OpenStreetMap Nomination Server returns results even if you dont know the ZIP Code and you can look at the results anyway. What if the user doesnt know the zip code but wants to find hist object?
I would try to search for that specific object anyway, especially because you said that some countries have zip codes partially.
If you simply return nothing te user doesnt know what went wrong and he wont know what to do.
That would depend on the use case. How easy is it for a user of the API to trigger that case? Is it a severe error which the user really should know how to avoid? Or is it something that is not entirely clear, where a user may know (or think he knows) a zipcode where officially there shouldn't be one? Does it come down to trial and error for the user how to retrieve correct results from your API? Is it a bad enough error that the user needs to be informed about it and that he needs to handle this on his side?
If you place this restriction in your API, consider that it will have to be clearly documented when this case is triggered, every user of the API will have to read and understand that documentation, it needs to be clear how to avoid the problem, it needs to be possible for the user to avoid the problem and every user will have to correctly implement extra code on his side to avoid this problem. Is it possible for the user to easily know which areas have zipcodes and which don't?
I think the mantra of "be flexible in what you accept, strict in what you output" applies...
Related
I have created an intent in lex called MinimumAgeIntent.
MinimumAgeIntent has 2 utterances:
1. what is the age limit
2. what is the minimum age a patient needs to be to partake in the study
When I type in the question "where is the capital of turkey" it is matching the minimum age intent. Why is this? What is going on it doesn't make any sense.
In the first picture you can see that it is returning the response as if it matches the minimum age intent.
In the second picture you can see the lambda logs which shows the intent in the request.
Lex maps intent not just for the utterances given, but instead it takes those as an example and try to match for similar user inputs. In your case this might have happened because of the utterances you have given for MinimumAgeIntent and other intents. When Lex try to map the intent based on the user input, it sees MinimumAgeIntent as the closest match.
Somethings which you can try
Use non-conflicting utterances for intents. And add different varieties of it such that it covers the user intention in general. Add at least 5 to 10 utterances for each intent.
Use slots appropriately and validate its value on your code.
Lex always gives the inputTranscript so you can validate it on your code. May be not the best idea, but still you can check for mandatory words (prefer validating slots), In your case "age" for MinimumAgeIntent. And respond back with an appropriate response.
Add another intent like InvalidUserInput and add common user inputs that the bot wont support and respond with a proper error message. Be very careful with this, do not do this unless you know what you are doing and there is no other way.
Disclaimers:
This is oriented towards Prestashop 1.5 but if the answer is: "this
is fixed in version 1.x" then I'll raise a petition to update our
shop.
I'm also tagging it as REST because I think I explained it throughly
enough so you don't need actual experience with Prestashop to understand it.
So in Prestashop we have this Web Services which lack support for use cases as simple as search by category.
1. Let's say you want to get all the products from categories 1, 3 and 17:
So what is the solution?
Well, you can do something in the lines of this answer: https://stackoverflow.com/a/34061229/4209853
where you get all the products from categories 1, 3 and 17 and then you make another call for products filtering by those ID's.
'filter[id]' => '['.implode('|',$productIDsArrayIGotBefore).']',
it's ugly and 20th centurish, but well... if it gets the job done... except it doesn't.
You see, this is a call for getting a resource, and someone somewhere decided:
Hey, we have all this nice HTTP action verbs, so let's use them for REST CRUD interfaces: POST for C, GET for R, PUT for U and DELETE for D. Neat.
And that's nice and all, but when combined with the lack of expressive power of Prestashop's Web Services means it's stupidly easy to run into, you guessed it? Yes, 414.
Error HTTP 414 Request URI too long
and we all know that modifying Apache so it accepts longer request URIs is not the neat scalable solution.
So we could try to split the array and make multiple calls, which is just conceptually ugh. Not just because of the performance hit of making multiple queries, but also because we would need to take into account the number of characters of all IDs concatenated to make the calculation of how many we can (safely) ask for in one call. And all that would have their own caveats, like:
2. What if we want to also filter them e.g. active=1?
Now we're in for a ride, because we can't know beforehand how many calls we will need to make.
Let's define:
N are the IDs I got from categories
n is the number of IDS I can safely ask for
T is the number of (filtered) products I want
tare the (filtered) products I already have
k are the (filtered) products we receive from the call
So we would end up with something like:
do{
n0= max(T-t, n);
k= get(products, n0);
t +=k;
}while(count(k)!=0 and count(t)<T and !empty(N))
..which is just... bonkers.
The only elegant solution I can come up with is creating a new Prestashop Web Service that acts as a wrapper, receiving the petition through POST and forwarding it to the Prestashop service.
But, befores that... do you have a better solution using some kind of RESTomancy I may be missing?
I'm designing a REST API where, amongst others, there are two objects.
Journey
Report
For each Journey there are many Reports enroute, and each Report has exactly one associated Journey.
A user might create a Journey using the API as follows...
POST /journey/
Then retrieve the details...
GET /journey/1226/
The first question is, if a user wanted to post an Report to their Journey, which is the 'correct' URL structure that the API should impose? This seems intuitive to me...
POST /journey/1226/report/
...or is this the case...
POST /report/
...whereby in the latter, the Journey ID is passed in the request body somewhere?
The second question is, how might one go about implementing the first case in a tool such as the Django REST framework?
Thanks!
The URL/URI structure is almost completely irrelevant. It is nice to be able to read it, or easily change or even guess it, but that is it. There is no "requirement" official or unwritten how they should look like.
The point is however, that you supply the URIs to your clients in your responses. Each GET will get you a representation that contains links to the next "states" that your client can reach. This means the server has full control over URI structure, the client usually has to only know the "start" or "homepage" URI, and that's it.
Here is an article which discusses this question, has some good points: http://www.ben-morris.com/hackable-uris-may-look-nice-but-they-dont-have-much-to-do-with-rest-and-hateoas/
Pass for the second question :) I didn't use that particular framework.
I'm helping develop a new API for an existing database.
I'm using Python 2.7.3, Django 1.5 and the django-rest-framework 2.2.4 with PostgreSQL 9.1
I need/want good documentation for the API, but I'm shorthanded and I hate writing/maintaining documentation (one of my many flaws).
I need to allow consumers of the API to add new "POS" (points of sale) locations. In the Postgres database, there is a foreign key from pos to pos_location_type. So, here is a simplified table structure.
pos_location_type(
id serial,
description text not null
);
pos(
id serial,
pos_name text not null,
pos_location_type_id int not null references pos_location_type(id)
);
So, to allow them to POST a new pos, they will need to give me a "pos_name" an a valid pos_location_type. So, I've been reading about this stuff all weekend. Lots of debates out there.
How is my API consumers going to know what a pos_location_type is? Or what value to pass here?
It seems like I need to tell them where to get a valid list of pos_locations. Something like:
GET /pos_location/
As a quick note, examples of pos_location_type descriptions might be: ('school', 'park', 'office').
I really like the "Browseability" of of the Django REST Framework, but, it doesn't seem to address this type of thing, and I actually had a very nice chat on IRC with Tom Christie earlier today, and he didn't really have an answer on what to do here (or maybe I never made my question clear).
I've looked at Swagger, and that's a very cool/interesting project, but take a look at their "pet" resource on their demo here. Notice it is pretty similar to what I need to do. To add a new pet, you need to pass a category, which they define as class Category(id: long, name: string). How is the consumer suppose to know what to pass here? What's a valid id? or name?
In Django rest framework, I can define/override what is returned in the OPTION call. I guess I could come up with my own little "system" here and return some information like:
pos-location-url: '/pos_location/'
in the generic form, it would be: {resource}-url: '/path/to/resource_list'
and that would sort of work for the documentation side, but I'm not sure if that's really a nice solution programmatically. What if I change the resources location. That would mean that my consumers would need to programmatically make and OPTIONS call for the resource to figure out all of the relations. Maybe not a bad thing, but feels like a little weird.
So, how do people handle this kind of thing?
Final notes: I get the fact that I don't really want a "leaking" abstaction here and have my database peaking thru the API layer, but the fact remains that there is a foreign_key constraint on this existing database and any insert that doesn't have a valid pos_location_type_id is raising an error.
Also, I'm not trying to open up the URI vs. ID debate. Whether the user has to use the pos_location_type_id int value or a URI doesn't matter for this discussion. In either case, they have no idea what to send me.
I've worked with this kind of stuff in the past. I think there is two ways of approaching this problem, the first you already said it, allow an endpoint for users of the API to know what is the id-like value of the pos_location_type. Many API's do this because a person developing from your API is gonna have to read your documentation and will know where to get the pos_location_type values from. End-users should not worry about this, because they will have an interface showing probably a dropdown list of text values.
On the other hand, the way I've also worked this, not very RESTful-like. Let's suppose you have a location in New York, and the POST could be something like:
POST /pos/new_york/
You can handle /pos/(location_name)/ by normalizing the text, then just search on the database for the value or some similarity, if place does not exist then you just create a new one. That in case users can add new places, if not, then the user would have to know what fixed places exist, which again is the first situation we are in.
that way you can avoid pos_location_type in the request data, you could programatically map it to a valid ID.
After reading an article on REST ("Restful Grails"), I have gotten the impression that it is not possible to truly conform to a REST style in a service that demands a lot of parameters. Is this so? All the examples I have seen so far seem to imply that true REST style services are "parameterless". Using parameters would be RPC-ish and not truly RESTful.
To be more specific, say we have a service that returns graph data for stock prices, and this service needs to know the start date, end date, the currency, stock name, and whatever else might be applicable. In any case, at least 4-5 parameters are needed to retrieve the information needed.
I would imagine the URL to be something like this : /stocks/YAHOO?startDate="2008-09-01"&endDate=...
("YAHOO" is here a made-up stock name).
Would this really be REST or is this more RPC-like, what the author of the aforementioned article calls "GETful" (i.e. just low ceremony rpc)?
You can see the querystring as a filter on the resource you are GETing. Here, your resource is the stock prices of yahoo. Doing a GET on that resource give you all the available data, or the most recents. The query string filter the prices you want. Content negociation allow you to change the representation, e.g. a png graph, a csv file, and so on. To add a price, simply POST a representation (e.g. CSV) to the same resource.
The "restfulness" is not realy in the URL itself, since URIs are obscures to client, but in the way you interact with resources themselves identified by their URI
Feel free to use as many parameters as you need to identify the resource you wish to access. REST doesn't care.
Why would you think it is not possible?
Google uses REST for their charts api, and they take alot of params:
http://chart.apis.google.com/chart?cht=bvg&chs=350x300&chd=t:20,35,10&chxr=1,0,40&chds=0,40&chco=FF0000|FFA000|00FF00&chbh=65,0,35&chxt=x,y,x&chxl=0:|High|Medium|Low|2:||Task+Priority||&chxs=2,000000,12&chtt=Tasks+on+my+To+Do+list&chts=000000,20&chg=0,25,5,5