On step 3 of this tutorial the author writes:
I personally would use the QueryParser when the search string is supplied by the user, and I’d use directly the API when the query is generated by your code.
Are there any benefits of using one over the other or is it just personal preference?
It's like the link says, if you want to allow users to enter custom searches as text string (i.e Name:matt, Age:[10 TO 80] use the QueryParser.
However if you only need to allow pre-defined queries, you can create them directly in your code.
So it depends what sort of queries you are using and how they are made, by the user, pre-defined etc
Related
I wonder how can I send a GET request to GitHub search API, specifically https://api.github.com/search/repositories and make the query to include several languages instead of one.
Here's my current query.
https://api.github.com/search/repositories?q=stars:%3E=1000+language:scala&sort=stars&order=desc&per_page=10
I have tried doing something like this but it didn't work as well
https://api.github.com/search/repositories?q=stars:%3E=1000+language:[scala, java]&sort=stars&order=desc&per_page=10
Thanks for your help
You need to pass in multiple language: element for being able to pass multiple languages to the query as per the doc.
For your specific case, the query would be :
https://api.github.com/search/repositories?q=stars:%3E=1000+language:scala+language:java&sort=stars&order=desc
with pagination applied it would be :
https://api.github.com/search/repositories?q=stars:%3E=1000+language:scala+language:java&sort=stars&order=desc&per_page=10
However, with pagination applied your search results will be limited in the browser.
Let's take the following resource in my REST API:
GET `http://api/v1/user/users/{id}`
In normal circumstances I would use this like so:
GET `http://api/v1/user/users/aabc`
Where aabc is the user id.
There are times, however, when I have had to design my REST API in a way that some extra information is passed with the ID. For example:
GET `http://api/v1/user/users/customer:1`
Where customer:1 denotes I am using an id from the customer domain to lookup the user and that id is 1.
I now have a scenario where the identifier is more than one key (a composite key). For example:
GET `http://api/v1/user/users/customer:1;type:agent`
My question: in the above URL, what should I use as the separator between customer:1 and type:agent?
According to https://www.ietf.org/rfc/rfc3986.txt I believe that the semi-colon is not allowed.
You should either:
Use parameters:
GET http://api/v1/user/users?customer=1
Or use a new URL:
GET http://api/v1/user/users/customer/1
But use Standards like this
("Paths tend to be cached, parameters tend to not be, as a general rule.")
Instead of trying to create a general structure for accessing records via multiple keys at once, I would suggest trying to think of this on more of a case-by-case basis.
To take your example, one way to interpret it is that you have multiple customers, and those customers each may have multiple user accounts. A natural hierarchy for this would be:
/customer/x/user/y
Often an elegant decision like this can be made, that not only solves the problem but also documents your data-model in a way that someone can easily see that users belong to customers via a 1-to-many relationship.
I wonder what saying good practices create REST API. Should or not I create URI which will allow get e.g. several specific users?
For example I mean:
/usermanagement/users/{j_goldman,wafik,morder}
And this uri will be returns 3 objects users for j_goldman, wafik and morder.
You can do this but it won't be restful IMHO. If you really need to do this you should think about remodeling your resource selections say, all three users you want to get belong to a particular group with id 111. Then you can do something like /groups/111 GET. If you cannot then I guess you should stick with restful solution and use three API calls to get users separately.
What you are doing is searching for a specific set of users. With a query parameter within your URL, you can achieve this.
To return a single user (id is 5):
/usermanagement/users/5
To return all users:
/usermanagement/users
To return a set of users based on search:
/usermanagement/users?username=
That way, your API is open to searching by a specified criteria which can also be extended.
Say, you wish to search by location:
/usermanagement/users?location=
Say, you wish to combine these:
/usermanagement/users?username={criteria}&location={criteria}
You may also want to expose a search endpoint itself:
/usermanagement/search
You might find other options here too:
RESTful URL design for search
This is sort of a follow-up to someone else's question about filtering/querying a list of cars. There the recommendation for a RESTful filtering request was to put filter expressions in the query of the URI, like this:
/cars?color=blue&type=sedan&doors=4
That's fine. But what if my filtering query becomes more complicated and I need to use Boolean operators, such as:
((color=blue OR type=sedan) AND doors=4) OR color=red
That is, I want to find a four-door blue car or a four-door sedan, but if the car is red I'll take it without caring about any of the other properties.
Is there any sort of convention for providing Boolean expressions in a RESTful URI's query parameters? I suppose I could by create some new querying expression language and put it in a POST, but that seems like a heavy and proprietary approach. How are others solving this?
It is perfectly okay to use
/cars/color:blue/type:sedan/doors:4
instead of
/cars?color=blue&type=sedan&doors=4
The URL standard says only that the path should contain the hierarchical part, and the query should contain the non-hierarchical. Since this is a map-reduce, using / is perfectly valid.
In your case you need a query language to describe your filters. If I were you I would copy an already existing solution, for example the query language of a noSQL database which has a REST API.
I think resource query language is what you need. I think you could use it like this:
/sthg?q="(foo=3|foo=bar)&price=lt=10"
or forget the default queryString parser, and like this:
/sthg?(foo=3|foo=bar)&price=lt=10
I suggest you to read the manual for further details.
Since I found no other URL compatible query language (yet), I think the only other option to serialize another query language and send it in a param, like SparSQL
http://localhost:8003/v1/graphs/sparql?query=your-urlencoded-query
by marklogic7. Hydra defines a freeTextQuery in its vocab, so they follow the same approach. But I'll ask Markus about this. It's a complicated topic, since according to the self-descriptive messages constraint you should describe somewhere what type of query language you use in the URL. I am not sure about this. :S
conclusion:
In order to support ad-hoc search queries we need a standard way to describe them in the link meta-data. Currently there are only a few standards about this. The most widely used standard is URI templates which does not support nested statements, operators, etc... for what I know. There is a draft called link descriptions which tries to fill the gap, but it is incomplete.
One possible workaround to define an URI template with a single q parameter which has rdf:type of x:SearchQuery and rdfs:range of xsd:string, and create another vocab about how to describe such a x:SearchQuery. After that the description could be used to build search forms, and validate queries sent to the server. Already existing queries could be supported too with this approach, so we don't need a new one.
So this problem can be solved with vocabs or new URI template standards.
I have seen many use a query string as you have provided - much like a SQL query string.
Here are just two examples:
Socrata (Open Data Portal company)'s SoQL (SQL variant): http://dev.socrata.com/consumers/cookbooks/querying-block-ranges.html
openFDA (API from fda.gov for open data) uses a similar string-based query parameter which maps to ElasticSearch queries, I believe: https://open.fda.gov/api/reference/#query-syntax
Try using 1 for true, 0 for false.
/_api/web/lists/getbytitle('XYZ')/items?$filter=Active eq 1
from the facebook documentation I know that
https://graph.facebook.com/search?q=conference&type=event
will perform a search of the word "conference" in the name and description of all public events.
is it possible to search for ALL the events without specifying the "query" parameter? Basically I don't want to limit the search to a keyword, I want to get ALL the public events (of course I will limit the research using the location field).
Also is there any list of possible categories I can use for searching between events? Using query sets a limitation in particular for the language (in different countries I have to search for different keywords,instead with a category I would fix this problem).
thanks a lot
Claus
You need to specify a q (query) parameter, but you can use the fields parameter to specify the fields in which you're searching. You may be able to achieve what you're trying to do by using this parameter.
See https://developers.facebook.com/docs/reference/api/#searching for more info.