DPS PitchLeads API Client Libraries

Client Libraries

General information

All libraries are "proofs of concept" that show how to make a simple interface between your application and the API server. They are provided with sample test code that accesses several features of a PitchLeads site using this interface.

For security reasons, it is recommended that the API and these libraries are only used in server-side applications in a client-server architecture. They should not be used in client-side applications.

Java Library

You can integrate this library into many Java applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

Note: the sample code requires the HttpComponents Client (http://hc.apache.org/httpcomponents-client) and JSON library (http://www.json.org/)

To use the library, you need to initialize a request handler and an API object:

DefaultHttpClient httpClient = new DefaultHttpClient(new ThreadSafeClientConnManager()); SkPublishAPI api = new SkPublishAPI(baseUrl + "/api/v1", accessKey, httpClient); api.setRequestHandler(new SkPublishAPI.RequestHandler() { public void prepareGetRequest(HttpGet request) { System.out.println(request.getURI()); request.setHeader("Accept", "application/json"); } });

Then, simply use the "api" object:

try { System.out.println("*** Dictionaries"); JSONArray dictionaries = new JSONArray(api.getDictionaries()); System.out.println(dictionaries); JSONObject dict = dictionaries.getJSONObject(0); System.out.println(dict); String dictCode = dict.getString("dictionaryCode"); System.out.println("*** Search"); System.out.println("*** Result list"); JSONObject results = new JSONObject(api.search(dictCode, "ca", 1, 1)); System.out.println(results); System.out.println("*** Spell checking"); JSONObject spellResults = new JSONObject(api.didYouMean(dictCode, "dorg", 3)); System.out.println(spellResults); System.out.println("*** Best matching"); JSONObject bestMatch = new JSONObject(api.searchFirst(dictCode, "ca", "html")); System.out.println(bestMatch); System.out.println("*** Nearby Entries"); JSONObject nearbyEntries = new JSONObject(api.getNearbyEntries(dictCode, bestMatch.getString("entryId"), 3)); System.out.println(nearbyEntries); } catch (Throwable t) { t.printStackTrace(); }

C# library

You can integrate this library into many C# applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

Note: the library requires Microsoft .NET Framework 4 (http://www.microsoft.com/en-us/download/details.aspx?id=17851). The sample is written as a Microsoft Visual Studio 10 project.

To use the library, you need to initialize an API object:

SkPublishAPI api = new SkPublishAPI(baseUrl + "/api/v1/", accessKey);

Then, simply use the "api" object:

Console.WriteLine("*** Dictionaries"); IList<IDictionary<string, object>> dictionaries = JsonToArray(api.GetDictionaries()); Console.WriteLine(ObjectToJson(dictionaries)); IDictionary<string, object> dictionary = dictionaries[0]; Console.WriteLine(ObjectToJson(dictionary)); string dictionaryCode = (string) dictionary["dictionaryCode"]; Console.WriteLine("*** Search"); Console.WriteLine("*** Result list"); IDictionary<string, object> results = JsonToObject(api.Search(dictionaryCode, "ca", 1, 1)); Console.WriteLine(ObjectToJson(results)); Console.WriteLine("*** Spell checking"); IDictionary<string, object> spellResults = JsonToObject(api.DidYouMean(dictionaryCode, "dorg", 3)); Console.WriteLine(ObjectToJson(spellResults)); Console.WriteLine("*** Best matching"); IDictionary<string, object> bestMatch =JsonToObject(api.SearchFirst(dictionaryCode, "ca", "html")); Console.WriteLine(ObjectToJson(bestMatch)); Console.WriteLine("*** Nearby Entries"); IDictionary<string, object> nearbyEntries = JsonToObject(api.GetNearbyEntries(dictionaryCode, (string) bestMatch["entryId"], 3)); Console.WriteLine(ObjectToJson(nearbyEntries));

Objective-C Library

The Objective-C library is presented as an Xcode solution. It contains a test program usable in command line.

Note: The library is developed on a Mac OS X (10.7.3) with Xcode 4.3 (4E109) and use JSON framework version 3.1.1 (https://github.com/stig/json-framework)

To use the library, you need to initialize an API object and a request handler:

SkPublishAPI *api = [[SkPublishAPI alloc] initWithUrlAndAcessKey:url :accessKey]; MyRequestHandler *requestHandler = [[MyRequestHandler alloc] init]; [api setRequestHandler: requestHandler];

Then, simply use the "api" object:

NSLog(@"*** Dictionaries"); result = [api getDictionaries]; NSLog(@"%@", result); NSDictionary *firstElement = [jsonUtils getFirstResult: result]; if(firstElement == NULL) { NSLog(@"No dictionary found."); return 1; } if(![firstElement objectForKey: @"dictionaryCode"]){ SBJsonWriter *jsonWriter = [[SBJsonWriter alloc] init]; NSMutableString *error = [[NSMutableString alloc] initWithString: @"dictionaryCode property was expected in the JSON object : "]; NSString *dictRespStr = [jsonWriter stringWithObject: firstElement]; [error appendString: dictRespStr]; NSLog(@"%@", error); return 1; } NSString *dictCode = [firstElement objectForKey: @"dictionaryCode"]; NSLog(@"*** Search"); NSLog(@"*** Result list"); result = [api search: dictCode : @"ca" : [NSNumber numberWithInt:1] : [NSNumber numberWithInt:1]]; NSLog(@"%@", result); NSLog(@"*** Spell checking"); result = [api didYouMean: dictCode : @"dorg": [NSNumber numberWithInt:3]]; NSLog(@"%@", result); NSLog(@"*** Best matching"); result = [api searchFirst: dictCode : @"ca" : @"html"]; NSLog(@"%@", result); firstElement = [jsonUtils getUniqueResult: result]; if(firstElement == NULL) { NSLog(@"No best matching found."); return 1; } if(![firstElement objectForKey: @"entryId"]){ SBJsonWriter *jsonWriter = [[SBJsonWriter alloc] init]; NSMutableString *error = [[NSMutableString alloc] initWithString: @"entryId property was expected in the JSON object : "]; NSString *dictRespStr = [jsonWriter stringWithObject: firstElement]; [error appendString: dictRespStr]; NSLog(@"%@", error); return 1; } NSString *entryId = [firstElement objectForKey: @"entryId"]; NSLog(@"*** Nearby Entries"); result = [api getNearbyEntries: dictCode : entryId : [NSNumber numberWithInt:3]]; NSLog(@"%@", result);

Perl Library

You can integrate this library into many Perl applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

Note: the sample code requires the LWP (http://search.cpan.org/~gaas/libwww-perl-6.04/), URI::Encode (http://search.cpan.org/~mithun/URI-Encode-0.07/) and JSON (http://search.cpan.org/~makamaka/JSON-2.53/) packages.

To use the library, you need to initialize a request handler and an API object:

package RequestHandler; sub new { my $class = shift; return bless { }, $class; } sub prepareGetRequest { my ($this, $request) = @_; print $request->uri."\n"; $request->header(Accept => 'application/json'); } package main; my $ua = new LWP::UserAgent(); my $api = new IDM::SkPublish::API($baseUrl."/api/v1", $accessKey, $ua); my $requestHandler = new RequestHandler; $api->setRequestHandler($requestHandler);

Then, simply use the "api" object:

print "*** Dictionaries\n"; my $dictionaries = decode_json($api->getDictionaries()); print Dumper($dictionaries)."\n"; my $dict = $dictionaries->[0]; print Dumper($dict); my $dictCode = $dict->{"dictionaryCode"}; print "*** Search\n"; print "*** Result list\n"; my $results = decode_json($api->search($dictCode, "ca", 1, 1)); print Dumper($results); print "*** Spell checking\n"; my $spellResults = decode_json($api->didYouMean($dictCode, "dorg", 3)); print Dumper($spellResults); print "*** Best matching\n"; my $bestMatch = decode_json($api->searchFirst($dictCode, "ca", "html")); print Dumper($bestMatch); print "*** Nearby Entries\n"; my $nearbyEntries = decode_json($api->getNearbyEntries($dictCode, $bestMatch->{"entryId"}, 3)); print Dumper($nearbyEntries);

PHP library

You can integrate this library into many PHP applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

You have also acces to a web sample, you can view how to have a dictionary list, how to use it for a select box, how to make a search and display the results or an entry.

Note: the sample code requires the cURL (http://php.net/manual/fr/book.curl.php) and JSON (http://php.net/manual/en/book.json.php) modules.

To use the library, you need to initialize a request handler and an API object:

class RequestHandler implements SkPublishAPIRequestHandler { public function prepareGetRequest($curl, $uri, &$headers) { print($uri."\n"); $headers[] = "Accept: application/json"; } } $requestHandler = new RequestHandler(); $api = new SkPublishAPI($baseUrl.'/api/v1', $accessKey); $api->setRequestHandler($requestHandler);

Then, simply use the "api" object:

print "*** Dictionaries\n"; $dictionaries = json_decode($api->getDictionaries(), true); var_dump($dictionaries); $dict = $dictionaries[0]; var_dump($dict); $dictCode = $dict["dictionaryCode"]; print "*** Search\n"; print "*** Result list\n"; $results = json_decode($api->search($dictCode, "ca", 1, 1), true); var_dump($results); print "*** Spell checking\n"; $spellResults = json_decode($api->didYouMean($dictCode, "dorg", 3), true); var_dump($spellResults); print "*** Best matching\n"; $bestMatch = json_decode($api->searchFirst($dictCode, "ca", "html"), true); var_dump($bestMatch); print "*** Nearby Entries\n"; $nearbyEntries = json_decode($api->getNearbyEntries($dictCode, $bestMatch->{"entryId"}, 3), true); var_dump($nearbyEntries);

Ruby Library

You can integrate this library into many Ruby applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

Note: the sample code requires the JSON for ruby (http://flori.github.com/json/) package. It was tested with Ruby 1.9.1 (http://www.ruby-lang.org/en/).

To use the library, you need to initialize a request handler and an API object:

uri = URI.parse(baseUrl) userAgent = Net::HTTP.new(uri.host, uri.port) userAgent.use_ssl = true userAgent.verify_mode = OpenSSL::SSL::VERIFY_NONE api = API.new(baseUrl+'/api/v1/', accessKey, userAgent)

Then, simply use the "api" object:

dictionaries = api.getDictionaries(); puts dictionaries dictionaries = JSON.parse(dictionaries) dict = dictionaries[0] puts dict dictCode = dict["dictionaryCode"]; puts dictCode puts "*** Search" puts "*** Result list" results = JSON.parse(api.search(dictCode, "ca", 1, 1)) puts results puts "*** Spell checking" spellResults = JSON.parse(api.didYouMean(dictCode, "dorg", 3)) puts spellResults puts "*** Best matching" bestMatch = JSON.parse(api.searchFirst(dictCode, "ca", "html")) puts bestMatch puts "*** Nearby Entries" nearbyEntries = JSON.parse(api.getNearbyEntries(dictCode, bestMatch["entryId"], 3)); puts nearbyEntries

Python Library

You can integrate this library into many Python applications that perform HTTPS requests.

In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.

Note: the library and sample are written for Python 2.6 (http://python.org/). The sample use the default JSON package (http://docs.python.org/2/library/json.html).

To use the library, you need to initialize a request handler and an API object:

api = API(baseUrl=baseUrl+'/api/v1/', accessKey=accessKey)

Then, simply use the "api" object:

print "*** Dictionaries" dictionaries = json.loads(api.getDictionaries()) print dictionaries dict = dictionaries[0] print dict dictCode = dict["dictionaryCode"] print "*** Search" print "*** Result list" results = json.loads(api.search(dictCode, "ca", 1, 1)) print results print "*** Spell checking" spellResults = json.loads(api.didYouMean(dictCode, "dorg", 3)) print spellResults print "*** Best matching" bestMatch = json.loads(api.searchFirst("british", "ca", "html"), "utf-8") print(bestMatch) print "*** Nearby Entries" nearbyEntries = json.loads(api.getNearbyEntries(dictCode, bestMatch["entryId"], 3)) print nearbyEntries

JavaScript library

The JavaScript library is designed to run in a JavaScript engine or server-side application and not from a website client side.

In the sample, using the library simplifies the request process to the API server and directly give you the result object in string form.

Note: the sample code was written for SilkJS (http://silkjs.org/) command-line usage and uses the cURL module (http://silkjs.org/documentation/builtin/curl)

Note: SilkJS is now deprecated. We keep the code and libraries available for reference and we will also investigate decafjs and NodeJS as alternative

(if you really need something working in Javascript you can use apiTestNode to replace apiTest.js on JS library, with nodeJS. This only require sync-request and fs module)

To use the library, you need to initialize a request handler and an API object:

var api = new SkPublishAPI ('https://'+baseUrl+'/api/v1', accessKey); var cURL = require('cURL'); api.setRequestHandler({ executeRequest : function(config) { var result = cURL(config); return result.responseText; }, prepareGetRequest : function(uri, accessKey) { var headers = { 'Host': baseUrl, 'accessKey': accessKey, 'Content-Type': 'application/json' }; var options = { url: uri, method: 'GET', headers: headers }; return options; } });

Then, simply use the "api" object:

print ("*** Dictionaries\n"); dictionaries = api.getDictionaries(); print (dictionaries+"\n"); dict = eval(dictionaries)[0]; for(var elt in dict){ infoVal = eval("dict."+elt); if (typeof infoVal == 'function') { continue; } print (elt + " : " + infoVal + " ; "); } print ("\n"); dictCode = dict.dictionaryCode; print ("*** Search\n"); print ("*** Result list\n"); results = api.search(dictCode, "ca", 1, 1); print (results+"\n"); print ("*** Spell checking\n"); spellResults = api.didYouMean(dictCode, "dorg", 3); print (spellResults+"\n"); print ("*** Best matching\n"); bestMatch = api.searchFirst(dictCode, "ca", "html"); print (bestMatch+"\n"); print ("*** Nearby Entries\n"); nearbyEntries = api.getNearbyEntries(dictCode, eval('['+bestMatch+']')[0].entryId, 3); print (nearbyEntries+"\n");

Use JavaScript library on a Website

For many reasons, in JavaScript, it is difficult to make requests on another domain than where the script is located and like said the above annotation, for security reason with API access key visibility, it is recommended to use API in server-side application, so if you want to use the API with javascript client-side application, you need to use a proxy to add your access key to user request.

flow diagram of requests
With proxyWithout proxy

The functionalities are the same than above, except the API object initialization.

Apache proxy

If you use Apache server and have access to your configuration you can configure it to use as a proxy.

Note: Some modules need to be activated to works: mod_headers (http://httpd.apache.org/docs/2.0/mod/mod_headers.html) and mod_proxy (http://httpd.apache.org/docs/2.4/fr/mod/mod_proxy.html).

RequestHeader set accessKey [access_key] ProxyPass /dictAPI http://[API_site_name]/api/v1

Next to use this proxy, you need to initialize an API object:

var api = new SkPublishAPI ('http://[your_site_name]/dictAPI', '');
Programmatic proxy: PHP

If you don't have access to your server configuration and want to use the JavaScript library to interract with the API, you need to use a programmatic proxy, in PHP for example.

When you use this proxy system, you can easily integrate your own authentication procedure or log system.

Note: The provided PHP proxy use the standard socket system of PHP so it must be working on almost all system.

You need to set the basic configuration to access API site:

$config = array( 'base_url' => 'https://[API_site_name]/', 'access_key' => 'access_key' );

To use this proxy, you need to initialize an API object:

var api = new SkPublishAPI ('./apiProxy.php', '');