Changeset 910 for trunk

Timestamp:

08/17/17 17:46:33 (7 years ago)

Author:

Kris Deugau

Message:

/trunk

Start adding POD semi-automatic documentation for APIs

Location:

trunk

Files:

• Makefile (modified) (4 diffs)
• cgi-bin/search-rpc.cgi (modified) (1 diff)

trunk/Makefile

@@ -27 +27 @@
 
 DESTDIR =
+
+GENDOCS = \
+        docs/search-rpc.html
 
 HTML = \
@@ -77 +80 @@
         cgi-bin/extras/network.tmpl
 
-DIRS = images templates cgi-bin cgi-bin/extras
+DIRS = docs images templates cgi-bin cgi-bin/extras
 
 MANIFEST = Makefile COPYING \
+        $(GENDOCS) \
         $(HTML) \
         $(JS) \
@@ -94 +98 @@
 
 list:
-        echo Makefile \
+        echo Makefile COPYING \
+        $(GENDOCS) \
         $(HTML) \
         $(JS) \
@@ -128 +133 @@
 dist:
         mkdir $(PKGNAME)-$(VERSION)
+        pod2html cgi-bin/search-rpc.cgi > docs/search-rpc.html
         tar cf - $(MANIFEST) | (cd $(PKGNAME)-$(VERSION); tar xf -)
         /usr/bin/perl -p -e 's/#VERSION#/$(VERSION)/g;s/#RELEASE#/$(RELEASE)/g;s/#BETA#//g' < $(PKGNAME).spec > $(PKGNAME)-$(VERSION)/$(PKGNAME).spec

trunk/cgi-bin/search-rpc.cgi

@@ -275 +275 @@
   return $result;
 } # rpc_search()
+
+
+__END__
+
+=pod
+
+=head1 IPDB XMLRPC Search
+
+This is a general-purpose search API for IPDB.  It is currently being extended based on requirements from other tools needing to 
+search for data in IPDB.
+
+It supports one XMLRPC sub, "search".
+
+The calling URL for this API should end with "/search-rpc.cgi".  If you are doing many requests, you should use the FastCGI variant 
+with .fcgi instead of .cgi.
+
+=head2 Calling conventions
+
+IPDB RPC services use "XMLRPC", http://xmlrpc.com, for data exchange.
+
+Arguments are passed in as a key-value list, and data is returned as an array of hashes in some form.
+
+=over 4
+
+=item Perl
+
+ use Frontier::Client;
+ my $server = Frontier::Client->new(
+   url => "http://server/path/search-rpc.cgi",
+ );
+ my %args = (
+   rpcsystem => 'somesystem',
+   rpcuser => 'someuser',
+   arg1 => 'val1',
+   arg2 => 'val2',
+ );
+ my $result = $server->call('ipdb.search', %args);
+
+=item Python 2
+
+ import xmlrpclib
+ server = xmlrpclib.Server("http://server/path/search-rpc.cgi")
+ result = server.ipdb.search(
+     'rpcsystem', 'comesystems',
+     'rpcuser', 'someuser',
+     'arg1', 'val1',
+     'arg2', 'val2',
+     )
+
+=item Python 3
+
+ import xmlrpc.client
+ server = xmlrpc.client.ServerProxy("http://server/path/search-rpc.cgi")
+ result = server.ipdb.search(
+     'rpcsystem', 'somesystem',
+     'rpcuser', 'someuser',
+     'arg1', 'val1',
+     'arg2', 'val2',
+     )
+
+=back
+
+=head3 Standard arguments
+
+The C<rpcsystem> argument is required, and C<rpcuser> is strongly recommended as it may be used for access control in some future 
+updates.
+
+C<rpcsystem> must match a configuration entry in the IPDB configuration, and a given string may only be used from an IP listed under 
+that configuration entry.
+
+=head2 Search fields and metaoperators
+
+Not all fields are exposed for search.  For most purposes these should be sufficient.
+
+=over 4
+
+=item cidr
+
+A full or partial CIDR network or IP address.  Valid formats include:
+
+=over 4
+
+=item Complete CIDR network, eg 192.168.2.0/24
+
+Returns an exact match for the passed CIDR network.
+
+If prefixed with "CONTAINS:", the containing netblocks up to the master block 
+will also be returned.
+
+If prefixed with "WITHIN:", any suballocations in that IP range will be returned.
+
+=item Partial/short CIDR specification with mask length, eg 192.168.3/27
+
+Returns all /27 assignments within 192.168.3.0/24.
+
+=item Partial/short CIDR specification, eg 192.168.4
+
+Returns all assignments matching that leading partial string.  Note that 192.168.4 will also return 192.168.40.0/24 through 
+192.168.49.0/24 as well as the obvious 192.168.4.0/24.
+
+=item Bare IP address with no mask, eg 192.168.5.42
+
+Returns all assignments containing that IP.
+
+=back
+
+=item custid
+
+Match on a customer ID.  Defaults to a partial match.
+
+=item type
+
+Match the two-character internal allocation type identifier.
+
+Defaults to an exact match.  Replace the first character with a dot or underscore, or leave it off, to match all subtypes of a 
+class;  eg .i will return all types of static IP assignments.
+
+A full list of current allocation types is available from the main RPC API's getTypeList sub.
+
+=item city
+
+Matches in the city string.
+
+=item description
+
+Matches in the description string.
+
+=item notes
+
+Matches in the notes field.
+
+=item available
+
+Only useful for static IPs.  For historic and architectural reasons, unallocated static IPs are included in general search results.  
+Specify 'y' or 'n' to return only unallocated or allocated static IPs respectively.
+
+To search for a free block, use the main RPC API's listFree or findAllocateFrom subs.
+
+=item order
+
+Sort order specification.  Send a string of comma-separated field names for subsorting.  Valid sort fields are cidr, custid, type, 
+city, and description.
+
+=back
+