Some Code Examples for the New Search API
By: Zhelko Dimic on March 8th, 2010
Posted in: OpenSRS Services
Tags: Development, Domains Service
Comments:
0
This is a quick example on how to use new features of the NAME_SUGGEST API lookup. As mentioned in my previous blog post, we added a new feature to the API that allows you to specify amount of time that you’re willing to wait for results. You would do it something like this:
{
protocol => 'XCP',
action => 'name_suggest',
object => 'domain',
attributes => {
searchstring => 'food toronto',
services => [ 'lookup', 'suggestion', 'premium',
'personal_names' ],
tlds => [ '.com', '.info', 'net', 'ca', 'co.in', '.co.uk', '.es' ],
max_wait_time => "1",
}
};
This search will check a limited number of TLDs (as specified in the call), but it will check regular lookups, name suggestions and premium names for each. Behind the scenes, all these checks will happen in parallel, after hitting the local cache and registry zone files that act as a secondary cache.
The parameter max_wait_time is the new feature. In this case, it means you’re willing to wait one second for response (as measured in our system; the total time for a response will include the roundtrip for the data to travel the Internet). We will collect all results that we can in that one second time period and return the results. The response will look something like this:
{
'protocol' => 'XCP',
'response_text' => 'Command completed successfully',
'is_search_completed' => '0',
'search_key' => 'Ln0ahqiOQ7H3Vab7sURVIronOks',
'action' => 'REPLY',
'response_code' => '200',
'attributes' => {
'lookup' => {
'count' => '10',
'response_text' => 'Command completed successfully.',
'response_code' => '200',
'is_success' => '1',
'items' => [
{
'domain' => 'foodtoronto.com',
'status' => 'available'
},
{
'domain' => 'foodtoronto.info',
'status' => 'available'
},
... (response cut here for clarity)
Now, many of the results will be determined and returned in one second, but it’s likely not all of them can be looked up in that time frame. However, even after we return result set, we continue collecting the rest of the results in the background.
If you’re building an AJAX interface, here is a neat trick you can use: Look at the parameter we returned called search_key, and you can reuse it:
{
protocol => 'XCP',
action => 'name_suggest',
object => 'domain',
attributes => {
'search_key' => 'Ln0ahqiOQ7H3Vab7sURVIronOks',
max_wait_time => "2",
}
};
In the call below you’re now using the search key parameter, and retrieving results that have already been collected for you. And you are also specifying that you’re willing to wait another two seconds. If you introduced some sleep() on your end before sending the second API call, you can drop this time too. At this point you will receive back something like:
{
'protocol' => 'XCP',
'request_response_time' => '0.002',
'response_text' => 'Command completed successfully',
'is_search_completed' => '1',
'action' => 'REPLY',
'response_code' => '200',
'attributes' => {
'lookup' => {
'count' => '10',
'response_text' => 'Command completed successfully.',
'response_code' => '200',
'is_success' => '1',
'items' => [
{
'domain' => 'foodtoronto.com',
'status' => 'available'
},
{
'domain' => 'foodtoronto.info',
'status' => 'available'
},
{
'domain' => 'foodtoronto.co.in',
'status' => 'available'
},
... (response cut here for clarity)
As you can see, another important addition is the new response parameter is_search_completed = 1. This value indicates that you have received the full result set, and that there is nothing outstanding. As long as there are still results to be obtained, is_search_completed will be 0, as in the first example…
Hope this helps. You can always visit the Developers/API section of the OpenSRS Forums to learn more about coding to the OpenSRS API.