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.
$ git clone https://github.com/UCLOrengoGroup/genome3d-openapi-client
$ cd genome3d-openapi-client
$ ./genome3d-api --help
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.
The Genome3D API consists of a number of operations that aim to perform tasks such as:
- "Show me all the annotations for a given UniProtKB accession"
- "Let me upload my predicted 3D models for a given UniProtKB sequence"
You can use your web browser to rummage through all the available operations:
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 ;)
$ 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 all available operations
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).
The name of the API operation you want to perform (see --list for a list of all operations and parameters)
Most operations require a particular UniProtKB accession to be specified.
Specify which resource to use (you can read data from any resource, but you can only write data to your own resource).
$ ./genome3d-api -o getDomainPrediction -u P00520 -r SUPERFAMILY
$ ./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 \
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
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.
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
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/
- Ian Sillitoe (author)
- Gerardo Tauriello
- Arun Prasad Pandurangan
- Daniel Buchan