Changeset 910


Ignore:
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:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/Makefile

    r904 r910  
    2727
    2828DESTDIR =
     29
     30GENDOCS = \
     31        docs/search-rpc.html
    2932
    3033HTML = \
     
    7780        cgi-bin/extras/network.tmpl
    7881
    79 DIRS = images templates cgi-bin cgi-bin/extras
     82DIRS = docs images templates cgi-bin cgi-bin/extras
    8083
    8184MANIFEST = Makefile COPYING \
     85        $(GENDOCS) \
    8286        $(HTML) \
    8387        $(JS) \
     
    9498
    9599list:
    96         echo Makefile \
     100        echo Makefile COPYING \
     101        $(GENDOCS) \
    97102        $(HTML) \
    98103        $(JS) \
     
    128133dist:
    129134        mkdir $(PKGNAME)-$(VERSION)
     135        pod2html cgi-bin/search-rpc.cgi > docs/search-rpc.html
    130136        tar cf - $(MANIFEST) | (cd $(PKGNAME)-$(VERSION); tar xf -)
    131137        /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

    r909 r910  
    275275  return $result;
    276276} # rpc_search()
     277
     278
     279__END__
     280
     281=pod
     282
     283=head1 IPDB XMLRPC Search
     284
     285This is a general-purpose search API for IPDB.  It is currently being extended based on requirements from other tools needing to
     286search for data in IPDB.
     287
     288It supports one XMLRPC sub, "search".
     289
     290The calling URL for this API should end with "/search-rpc.cgi".  If you are doing many requests, you should use the FastCGI variant
     291with .fcgi instead of .cgi.
     292
     293=head2 Calling conventions
     294
     295IPDB RPC services use "XMLRPC", http://xmlrpc.com, for data exchange.
     296
     297Arguments are passed in as a key-value list, and data is returned as an array of hashes in some form.
     298
     299=over 4
     300
     301=item Perl
     302
     303 use Frontier::Client;
     304 my $server = Frontier::Client->new(
     305   url => "http://server/path/search-rpc.cgi",
     306 );
     307 my %args = (
     308   rpcsystem => 'somesystem',
     309   rpcuser => 'someuser',
     310   arg1 => 'val1',
     311   arg2 => 'val2',
     312 );
     313 my $result = $server->call('ipdb.search', %args);
     314
     315=item Python 2
     316
     317 import xmlrpclib
     318 server = xmlrpclib.Server("http://server/path/search-rpc.cgi")
     319 result = server.ipdb.search(
     320     'rpcsystem', 'comesystems',
     321     'rpcuser', 'someuser',
     322     'arg1', 'val1',
     323     'arg2', 'val2',
     324     )
     325
     326=item Python 3
     327
     328 import xmlrpc.client
     329 server = xmlrpc.client.ServerProxy("http://server/path/search-rpc.cgi")
     330 result = server.ipdb.search(
     331     'rpcsystem', 'somesystem',
     332     'rpcuser', 'someuser',
     333     'arg1', 'val1',
     334     'arg2', 'val2',
     335     )
     336
     337=back
     338
     339=head3 Standard arguments
     340
     341The C<rpcsystem> argument is required, and C<rpcuser> is strongly recommended as it may be used for access control in some future
     342updates.
     343
     344C<rpcsystem> must match a configuration entry in the IPDB configuration, and a given string may only be used from an IP listed under
     345that configuration entry.
     346
     347=head2 Search fields and metaoperators
     348
     349Not all fields are exposed for search.  For most purposes these should be sufficient.
     350
     351=over 4
     352
     353=item cidr
     354
     355A full or partial CIDR network or IP address.  Valid formats include:
     356
     357=over 4
     358
     359=item Complete CIDR network, eg 192.168.2.0/24
     360
     361Returns an exact match for the passed CIDR network.
     362
     363If prefixed with "CONTAINS:", the containing netblocks up to the master block
     364will also be returned.
     365
     366If prefixed with "WITHIN:", any suballocations in that IP range will be returned.
     367
     368=item Partial/short CIDR specification with mask length, eg 192.168.3/27
     369
     370Returns all /27 assignments within 192.168.3.0/24.
     371
     372=item Partial/short CIDR specification, eg 192.168.4
     373
     374Returns all assignments matching that leading partial string.  Note that 192.168.4 will also return 192.168.40.0/24 through
     375192.168.49.0/24 as well as the obvious 192.168.4.0/24.
     376
     377=item Bare IP address with no mask, eg 192.168.5.42
     378
     379Returns all assignments containing that IP.
     380
     381=back
     382
     383=item custid
     384
     385Match on a customer ID.  Defaults to a partial match.
     386
     387=item type
     388
     389Match the two-character internal allocation type identifier.
     390
     391Defaults to an exact match.  Replace the first character with a dot or underscore, or leave it off, to match all subtypes of a
     392class;  eg .i will return all types of static IP assignments.
     393
     394A full list of current allocation types is available from the main RPC API's getTypeList sub.
     395
     396=item city
     397
     398Matches in the city string.
     399
     400=item description
     401
     402Matches in the description string.
     403
     404=item notes
     405
     406Matches in the notes field.
     407
     408=item available
     409
     410Only useful for static IPs.  For historic and architectural reasons, unallocated static IPs are included in general search results. 
     411Specify 'y' or 'n' to return only unallocated or allocated static IPs respectively.
     412
     413To search for a free block, use the main RPC API's listFree or findAllocateFrom subs.
     414
     415=item order
     416
     417Sort order specification.  Send a string of comma-separated field names for subsorting.  Valid sort fields are cidr, custid, type,
     418city, and description.
     419
     420=back
     421
Note: See TracChangeset for help on using the changeset viewer.