search

UCLOrengoGroup / genome3d-openapi-client

Tool to interact with the Genome3D API
GNU General Public License v3.0
5 stars 1 forks source link

readme

Genome3D API Client

Tool to provide easy access with the Genome3D API on the command line.

Please regularly update your local repository to get the latest changes.

Please log problems, suggestions, feature requests as GitHub Issues.

Getting started

Get code

$ git clone https://github.com/UCLOrengoGroup/genome3d-openapi-client
$ cd genome3d-openapi-client

Run code

$ ./genome3d-api --help

Dependencies

This project aims to work as a standalone tool: the only dependency should be having access to a relatively modern version of Perl. If running the command above produces an error, then head over to the Troubleshooting section or create an issue in GitHub.

Overview

The Genome3D API consists of a number of operations that aim to perform tasks such as:

You can use your web browser to rummage through all the available operations:

http://head.genome3d.eu/api

An equivalent list can be generated by the command-line tool genome3d-api in this project:

$ ./genome3d-api --list

The tool genome3d-api aims to make communicating with the Genome3D API as convenient as possible. However, since the API has been defined using OpenAPI standards, you should be able to point any OpenAPI compatible client to the following specification:

http://head.genome3d.eu/api/openapi.json

This is a polite way of saying that if you don't like this code, you are more than welcome to write your own ;)

Usage

$ genome3d-api -h
USAGE: genome3d-api [-h] [long options ...]

    --mode=String            specify the mode for the data source
                             (daily|head|release) [daily]

    -l --list                list all the available operations

    -o --operation=String    specify operation (eg 'listResources')
    --pdbfiles=[Strings]     specify pdb files for structural prediction
    -r --resource_id=String  specify resource identifier (eg 'SUPERFAMILY')
    -u --uniprot_acc=String  specify uniprot identifier (eg 'P00520')
    --xmlfile=String         specify xml file for domain prediction

    --base_path=String       override the default base path [/api])
    --conf=String            override the default config file
                             [client_config.json]
    --host=String            override the default host (eg 'localhost:5000')

    -q --quiet               output fewer details
    -v --verbose             output more details

    --usage                  show a short help message
    -h                       show a compact help message
    --help                   show a long help message
    --man                    show the manual

Many of these options can be safely ignored, the following will be used frequently.

--list

List all available operations

--mode=<daily|head|release>

IMPORTANT: The mode determines which backend database will be used for API calls. The default setting is --mode=daily which is useful for testing only (since all changes are wiped every day).

Mode Role Read/Write Description Web
daily (default) TESTING Read/Write Updated every day from head link
head LIVE Read/Write Contains data that will make it into the next release link
latest RELEASE Read Only Contains data from the most recent release (ie the data currently available on the main Genome3D web site) link

Note: corresponding web pages are available for each of these modes (web link above).

-o --operation

The name of the API operation you want to perform (see --list for a list of all operations and parameters)

-u --uniprot_acc

Most operations require a particular UniProtKB accession to be specified.

-r --resource_id

Specify which resource to use (you can read data from any resource, but you can only write data to your own resource).

Examples

Show all the predicted domain annotations for the UniProtKB accession P00520:

$ ./genome3d-api -o getDomainPrediction -u P00520 -r SUPERFAMILY

Upload 3D structure predictions (based on the UniProtKB accession P00520) to the Genome3D server:

$ ./genome3d-api -o updateStructurePrediction -u P00520 -r SUPERFAMILY \
  --pdbfiles=./example_data/SUPERFAMILY/P00520_62_147.pdb \
  --pdbfiles=./example_data/SUPERFAMILY/P00520_122_262.pdb \

Note: in this case, the two PDB files correspond to two separate model regions of the UniProtKB sequence.

Upload domain start/stop predictions (based on the UniProtKB accession P00520) to the Genome3D server:

$ ./genome3d-api -o updateDomainPrediction -u P00520 -r SUPERFAMILY \
  --xmlfile=./example_data/SUPERFAMILY/P00520.xml \

Actually do all these for real

Remember: by default this tool uses --mode=daily so any changes you make will be lost when the database refreshes every day (at midnight). When you're sure you want to make your changes for real, you need to add the option:

--mode=head

Authentication

Since the API lets users make changes to the Genome3D database, it is important to make sure people only change their own data. As such, each contributing group needs to have their own uniquely identifying information (which will be sent out seperately to each contributor and should be kept secret).

Once you have been given your details, you should ammend the file client_config.json.

{
  "resource":      "<RESOURCE_ID>",
  "username":      "<RESOURCE_USER>",
  "password":      "<RESOURCE_SECRET>",
  "client_secret": "<CLIENT_SECRET>"
}

This will now allow you to perform authenticated operations (ie ADD, UPDATE, DELETE your own data) as well as the GET operations that allow everyone to read information from the database.

Troubleshooting

Can't locate <Module>.pm in @INC ...

This tool is written in Perl and depends on a number of useful modules. These modules have been included as part of this project, however if this error is being reported then it suggests that your machine is having problems accessing these dependencies (probably due to differences in OS/architecture).

If you have the cpanm tool available, then executing the following in the root directory of this project should help:

$ cpanm -L extlib --installdeps .

If this now works for you, then please consider submitting a PR with the changes in ./extlib.

If you do not have cpanm but have cpan, you can install cpanm as follows:

$ cpan -i App::cpanminus

Sorry, there was an error trying to authentication this client...

Any operation that involves 'writing' data to the Genome3D server requires authentication (to prove you have appropriate permissions to add/update/delete data). See the authentication section.

perl: symbol lookup error: genome3d-openapi-client/extlib/lib/perl5/x86_64-linux-thread-multi/auto/Unicode/LineBreak/LineBreak.so: undefined symbol: Perl_xs_handshake

linebreak.so provided by perl the module Unicode::Linebreak which is bundled in the extlib. However this module has strict compatibilities with specific perl versions and after installing the extlib dependencies for the client you may still see this failure. You can resolve this by installing the package for your local perl version and removing the version bundled in the extlibs.

cpan -i Unicode::Linebreak
rm -r extlib/lib/perl5/x86_64-linux-gnu-thread-multi/Unicode/
rm -r extlib/lib/perl5/x86_64-linux-thread-multi/Unicode/

Contributors

Acknowledgements