web services

As promised, I have written a web services module to attach on to Gedcom.pm.
I'll not say much about it except that the documentation is below, it is up and
running at http://pjcj.sytes.net:8585/ws/ and I would welcome comments about
its usability or otherwise.

This will be part of the next release of Gedcom.pm, which I hope to make
some time between now and early new year, depending on my network
connectivity over Christmas, but if anyone can't wait that long, mail me
and you can have a snapshot.

I had hoped to write some snazzy, or at least basically functional ajaxy thingy
to show that it actually works, but I've not got around to it yet, so I thought
it would be better to get this out.

This is running on my server at home, so if it goes down and there's no one
around to restart it, I apologise in advance.

Enjoy,


NAME
    Gedcom::WebServices - Basic web service routines for Gedcom.pm

    Version 1.1502 - 20th December 2005

SYNOPSIS
     wget -qO - http://www.example.com/ws/plain/my_family/i9/name

DESCRIPTION
    This module provides web service access to a GEDCOM file in conjunction
    with mod_perl.  Using it, A request for imformation can be made in the
    form of a URL specifying the GEDCOM file to be used, which information
    is required and the format in which the information is to be delivered. 
    This information is then returned in the specified format.

    There are currently three supported formats:

    *   plain - no markup

    *   XML

    *   JSON

  URLs
    The format of the URLs used to access the web services are:

     $BASEURL/$FORMAT/$GEDCOM/$XREF/requested/information
     $BASEURL/$FORMAT/$GEDCOM?search=search_criteria

    BASEURL
        The base URL to access the web services.

    FORMAT
        The format in which to return the results.

    GEDCOM
        The name of the GEDCOM file to use (the extension .ged is assumed).

    XREF
        The xref of the record about which information is required.  XREFs
        can be obtained initially from a search, and subsequently from
        certain queries.

    requested/information
        The information requested.  This is in the same format as that taken
        by the get_value method.

    search_criteria
        An individual to search for.  This is in the same format as that
        taken by the get_individual method.

EXAMPLES
     $ wget -qO - 'http://pjcj.sytes.net:8585/ws/plain/royal92?search=elizabeth_ii'
     /ws/plain/royal92/I52

     $ wget -qO - http://pjcj.sytes.net:8585/ws/plain/royal92/I52
     0 @I52@ INDI
     1   NAME Elizabeth_II Alexandra Mary/Windsor/
     1   TITL Queen of England
     1   SEX F
     1   BIRT
     2     DATE 21 APR 1926
     2     PLAC 17 Bruton St.,London,W1,England
     1   FAMS @F14@
     1   FAMC @F12@

     $ wget -qO - http://pjcj.sytes.net:8585/ws/plain/royal92/I52/name
     Elizabeth_II Alexandra Mary /Windsor/

     $ wget -qO - http://pjcj.sytes.net:8585/ws/plain/royal92/I52/birth/date
     21 APR 1926

     $ wget -qO - http://pjcj.sytes.net:8585/ws/plain/royal92/I52/children
     /ws/plain/royal92/I58
     /ws/plain/royal92/I59
     /ws/plain/royal92/I60
     /ws/plain/royal92/I61

     $ wget -qO - http://pjcj.sytes.net:8585/ws/json/royal92/I52/name
     {"name":"Elizabeth_II Alexandra Mary /Windsor/"}

     $ wget -qO - http://pjcj.sytes.net:8585/ws/xml/royal92/I52/name
     <NAME>Elizabeth_II Alexandra Mary /Windsor/</NAME>

     $ wget -qO - http://pjcj.sytes.net:8585/ws/xml/royal92/I52
     <INDI ID="I52">
       <NAME>Elizabeth_II Alexandra Mary/Windsor/</NAME>
       <TITL>Queen of England</TITL>
       <SEX>F</SEX>
       <BIRT>
         <DATE>21 APR 1926</DATE>
         <PLAC>17 Bruton St.,London,W1,England</PLAC>
       </BIRT>
       <FAMS REF="F14"/>
       <FAMC REF="F12"/>
     </INDI>

CONFIGURATION
    Add a section similar to the following to your mod_perl config:

     PerlWarn On
     PerlTaintCheck On

     PerlPassEnv GEDCOM_TEST

     <IfDefine GEDCOM_TEST>
         <Perl>
             $Gedcom::TEST = 1;
         </Perl>
     </IfDefine>

     <Perl>
         use Apache::Status;

         $ENV{PATH} = "/bin:/usr/bin";
         delete @ENV{"IFS", "CDPATH", "ENV", "BASH_ENV"};

         $Gedcom::DATA = $Gedcom::ROOT;  # location of data stored on server

         use lib "$Gedcom::ROOT/blib/lib";
         use Gedcom::WebServices;

         my $handlers =
         [ qw
           (
               plain
               xml
               json
           )
         ];

         eval Gedcom::WebServices::_set_handlers($handlers);
         # use Apache::PerlSections; print STDERR Apache::PerlSections->dump;
     </Perl>

     PerlTransHandler Gedcom::WebServices::_parse_uri

BUGS
    Very probably.

    See the BUGS file.  And the TODO file.

VERSION
    Version 1.1502 - 20th December 2005

LICENCE
    Copyright 2005, Paul Johnson ([email protected])

    This software is free.  It is licensed under the same terms as Perl
    itself.

    The latest version of this software should be available from my
    homepage: http://www.pjcj.net


-- 
Paul Johnson - [email protected]
http://www.pjcj.net