Check out the
headlines
headlines
Paglo API
The Paglo Application Programming Interface (API) supports requests from computer programs, from both Paglo and other third parties. You can write small scripts and programs that submit data to the Paglo API. The API makes it easy to submit PQL queries against your Paglo database and to add documents to it.
Services
All calls to the Paglo API use the HTTP POST command to post
data to the following URL:
https://api.paglo.com/api/
The Paglo API includes the following services:
paglo.ping— Tests whether you can reach the Paglo API, and validates your data key or API key.paglo.query— Submits a PQL statement to your Paglo Search Index and gets results.paglo.submit— Submits data into your Paglo Search Index beyond what your Crawler collected, which makes that data searchable.
paglo.ping
The paglo.ping performs a basic ping test to verify that you can reach
the Paglo API and that your data key or API key is valid.
|
Name |
Value |
Description |
|
method |
|
Required: API method to invoke on the server. |
|
v |
|
Optional: version of the API to invoke. Currently, |
|
|
[API key or data key] |
Required: API key or data key to authenticate this request as valid and to permit access to your company's Paglo database. You can view your data key on your Paglo Accounts page. |
Example 1
This example pings the company's Paglo database using the
paglo_api.rb.
#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your data key or api key goes here")
resp = p.ping
puts "Response: #{resp}"
Result 1
The result of the ping looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<ping_response xmlns="http://paglo.com/xml/1.0/">
<pong></pong>
<arg>
<name>v</name>
<value>1.0</value>
</arg>
<arg>
<name>api_key</name>
<value>your data key or api key</value>
</arg>
<arg>
<name>action</name>
<value>index</value>
</arg>
<arg>
<name>method</name>
<value>paglo.ping</value>
</arg>
<arg>
<name>controller</name>
<value>api</value>
</arg>
</ping_response>
Example 2
This example pings your company's Paglo database using net/http,
net/https, and cgi.
#!/usr/bin/env ruby
require 'net/http'
require 'net/https'
require 'cgi'
h = Net::HTTP.new("app.paglo.com", 443)
h.use_ssl = true
resp,body = h.post("/api",
"method=paglo.ping" +
"&api_key=" + CGI.escape("your data key or api key"))
puts "Code: #{resp.code}"
puts "Message: #{resp.message}"
puts "Body: #{body.to_s}"
Result 2
This example produces the same result as in Example 1.
paglo.query
Use the paglo.query to submit a PQL statement to your company's
Paglo database, such as SELECT or DELETE.
(To make a PQL MERGE, INSERT, or UPDATE statement,
use paglo.submit.)
This is very useful if you want to develop applications that extend the use and functionality of Paglo.
|
Name |
Value |
Description |
|
method |
|
Required: API method to invoke on the server. |
|
v |
|
Optional: version of the API to invoke. Currently, |
|
|
|
Required: API key or data key to authenticate this request as valid and to permit access to your company's Paglo database. You can view your data key on your Paglo Accounts page (https://app.paglo.com/user/edit). |
|
query |
|
Required: a properly formatted, URL-escaped PQL query or statement. |
|
return_table |
|
Optional: Value that returns the results in a table of values. |
Example 1
This example submits a simple query to find everything about Node #2886.
#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your api key or data key goes here.")
resp = p.query(:query => "select interface from 2886")
puts "Response: #{resp}"
Result 1
Of course, the result of this example query depends on whether your database
contains a node with an identical number of 2886 or not. Still, it is useful
to examine a sample result. In the following sample, standard parameters are
returned as arg nodes, as well as several row nodes,
one row for each item that matches the PQL statement.
This is most useful for SELECT statements. PQL INSERT,
MERGE, UPDATE, and DELETE have a
<response></response> node, but are empty. For MERGE
statements, the paglo.submit
API is more appropriate than paglo.query.
<?xml version="1.0" encoding="UTF-8"?>
<query_response xmlns="http://paglo.com/xml/1.0/">
<response>
<row>
<value name="interface/interface/inet/ip_address">10.10.10.10</value>
<value name="interface/interface/mac_address">00:01:02:03:04:05</value>
</row>
</response>
<arg>
<name>v</name>
<value>1.0</value>
</arg>
<arg>
<name>api_key</name>
<value>the api key or data key you used appears here</value>
</arg>
<arg>
<name>action</name>
<value>index</value>
</arg>
<arg>
<name>method</name>
<value>paglo.query</value>
</arg>
<arg>
<name>controller</name>
<value>api</value>
</arg>
<arg>
<name>query</name>
<value>select interface from 2886</value>
</arg>
</query_response>
Example 2
Example 1 returns its results in the form of a table. This example returns the same results in tree format:
SELECT interface
FROM /network/device
WHERE system/name='smith-desktop'
Result 2
Here are the results in the form of a tree:
<?xml version="1.0" encoding="UTF-8"?>
<query_response xmlns="http://paglo.com/xml/1.0/">
<response>
<tree name="row">
<tree name="interface">
<value name="mac_address">
00:01:02:03:04:05
</value>
<value name="name">
eth0
</value>
<value name="type">
6
</value>
<value name="speed">
10000000
</value>
<value name="out_errors">
0
</value>
<value name="in_errors">
0
</value>
<value name="mtu">
1500
</value>
<value name="out_octets">
1157447151
</value>
<value name="in_octets">
214365650
</value>
<value name="descr">
eth0
</value>
<tree name="inet">
<value name="ip_address">
10.10.10.10
</value>
<value name="netmask">
255.255.255.255
</value>
</tree>
<value name="oper_status">
1
</value>
<value name="admin_status">
1
</value>
</tree>
</tree>
</response>
<arg>
<name>
v
</name>
<value>
1.0
</value>
</arg>
<arg>
<name>
api_key
</name>
<value>
your api key appears here
</value>
</arg>
<arg>
<name>
action
</name>
<value>
index
</value>
</arg>
<arg>
<name>
method
</name>
<value>
paglo.query
</value>
</arg>
<arg>
<name>
controller
</name>
<value>
api
</value>
</arg>
<arg>
<name>
query
</name>
<value>
select interface from /network/device
where system/name='smith-desktop'
</value>
</arg>
</query_response>
paglo.submit
The paglo.submit adds, merges, or updates the data in your Paglo
account. This API is the equivalent of sending a PQL INSERT,
MERGE, or UPDATE statement.
This is especially useful if you want the ability to search some type of
data that the Paglo Crawler does not currently gather. You have the option
of writing a Crawler plugin
to extend the Crawler, of course. But you may already have a data-gathering
system such as mrtg or an rrdtool-based system. If
so, you can enable your legacy system to communicate with Paglo by writing
small scripts and programs that submit data to the Paglo API. Then, with a
few lines of code and the paglo.submit, you can send that data
to Paglo to index it, where you can search it.
|
Name |
Value |
Description |
|
method |
|
Required: API method to invoke on the server. |
|
v |
|
Optional: version of the API to invoke. Currently, |
|
|
[API key or data key] |
Required: API key or company data key to authenticate this request as valid and to permit access to your company's Paglo database. You can view your data key on your Paglo Accounts page (https://app.paglo.com/user/edit). |
|
data |
[URL-encoded string of data] |
Required: a properly formatted, URL-encoded string of data to update PQL
with, such as a valid data for the |
|
at |
[comma-separated list of integers indicating year, month, day, hour, minute, and seconds] |
Optional: The |
Example 1
Note that the data that you submit via paglo.submit must be URL-encoded,
and it must be valid for the VALUES clause of a PQL MERGE
statement. For example, if you submit {a[b='2'] => {b => '3'}} as your
data, Paglo inserts this data into a PQL MERGE statement like this:
MERGE INTO / VALUES {a[b='2'] => {b => '3'}}. If this does not form
a syntactically correct PQL statement, an error is returned.
This example submits data to the company's Paglo database with a simple ruby
script using net/http, net/https, and cgi.
#!/usr/bin/env ruby
require 'net/http'
require 'net/https'
require 'cgi'
h = Net::HTTP.new("api.paglo.com", 443)
h.use_ssl = true
resp,body = h.post("/api",
"method=paglo.submit&v=1.0&api_key=" +
CGI.escape("your api or data key goes here") +
"&data=" + CGI.escape("{a[b='2'] => {b => '3'}}"))
puts "Code: #{resp.code}"
puts "Message: #{resp.message}"
puts "Body: #{body.to_s}"
Result
Unlike the other Paglo APIs, the result of a successful paglo.submit is
short. Paglo does not repeat your entire submission in the response, unless
the submission fails (see Error messages).
The following result indicates a successful submission:
<?xml version="1.0" encoding="UTF-8"?> <submit_response xmlns="http://paglo.com/xml/1.0/"> <response>Data submitted for indexing.</response> </submit_response>
Example 2
This example submits data to the company's Paglo database using paglo_api.
#!/usr/bin/env ruby
#
require 'paglo_api'
p = Paglo::Session.new("your api or data key goes here")
resp = p.submit(:data => "{a[b='2'] => {b => '3'}}")
puts "Response: #{resp}"
Result
This example produces the same result as in Example 1.
Error messages
Paglo does not repeat your entire submission in the response, unless
the submission fails. If the submission fails, Paglo returns the submission
and indicates where the failure occurred. The paglo.submit
can result in one of two possible return codes:
|
Code |
Description |
|
500 |
The API call failed because of an internal server error. |
|
200 |
No server error occurred, but doublecheck the result code for
any |
Example
The following example shows a paglo.submit call that returns
Code 200, but contains an error code indicating an invalid API key:
<?xml version="1.0" encoding="UTF-8"?>
<error_response xmlns="http://paglo.com/xml/1.0/">
<error_code>2</error_code>
<error_message>API key is not valid</error_message>
<arg>
<name>v</name>
<value>1.0</value>
</arg>
<arg>
<name>api_key</name>
<value>thisisnotavalidkey</value>
</arg>
<arg>
<name>action</name>
<value>index</value>
</arg>
<arg>
<name>method</name>
<value>paglo.submit</value>
</arg>
<arg>
<name>controller</name>
<value>api</value>
</arg>
<arg>
<name>data</name>
<value>{a[b='2'] => {b => '3'}}</value>
</arg>
</error_response>
