Rat Genome Database PHP API Client Documentation

Introduction¶

The Tectalic Rat Genome Database REST API Client is a package that provides a convenient and straightforward way to interact with the Rat Genome Database API from your PHP application.

You can purchase this package from https://tectalic.com/apis/rat-genome-database.

Installation¶

System Requirements¶

• PHP version 7.2.5 or newer (including PHP 8.0 and 8.1)
• PHP JSON extension installed if using PHP 7.x. As of PHP 8.0, this extension became a core PHP extension so is always enabled.
• A PSR-18 compatible HTTP client such as ‘Guzzle’ or the ‘Symfony HTTP Client’.

Composer Installation¶

To install this package into your PHP project, we recommend using Composer.

Please see the detailed instructions on configuring your project to access the Tectalic Composer repository.

You will need to log into the Tectalic account that purchased the Tectalic Rat Genome Database REST API Client package to access these instructions.

Once you have followed the above instructions, install the package into your project:

composer require tectalic/rat-genome-database

Manual Installation¶

If you aren’t using Composer in your PHP project, you can choose to Download the latest release and install it into your PHP project manually.

If doing this, you will need to ensure that all dependencies listed in the package’s composer.json file are also installed.

Usage¶

After installing the Tectalic Rat Genome Database REST API Client package into your project, ensure you also have a compatible PSR-18 HTTP client such as ‘Guzzle’ or the Symfony ‘HTTP Client’.

You can use the following code sample and customize it to suit your application.

// Load your project's composer autoloader (if you aren't already doing so).
require_once(__DIR__ . '/vendor/autoload.php');

use Symfony\Component\HttpClient\Psr18Client;
use Tectalic\RatGenomeDatabase\Client;
use Tectalic\RatGenomeDatabase\Manager;
 
// Build a Tectalic Rat Genome Database REST API Client globally.
$httpClient = new Psr18Client();
Manager::build($httpClient);
 
// or
 
// Build a Tectalic Rat Genome Database REST API Client manually.
$httpClient = new Psr18Client();
$client = new Client($httpClient, Manager::BASE_URI);

Client Class¶

The primary class you will interact with is the Client class (Tectalic\RatGenomeDatabase\Client).

This Client class also contains the helper methods that let you quickly access the 75 API Handlers.

Please see below for a complete list of supported handlers and methods.

Supported API Handlers and Methods¶

This package supports 100 API Methods, which are grouped into 75 API Handlers.

See the table below for a full list of API Handlers and Methods.

API Handler Class and Method Name	Description	API Verb and URL
Agr::getGenesForLatestAssemblyUsingGet()	Get gene records submitted by RGD to AGR by taxonId	GET /agr/{taxonId}
AgrAffectedGenomicModels::getAffectedGenomicModelsUsingGet()	Get affected genomic models (rat strains with gene alleles) submitted by RGD to AGR by taxonId	GET /agr/affectedGenomicModels/{taxonId}
AgrAlleles::getAllelesForTaxonUsingGet()	Get gene allele records submitted by RGD to AGR by taxonId	GET /agr/alleles/{taxonId}
AgrExpression::getExpressionForTaxonUsingGet()	Get expression annotations submitted by RGD to AGR by taxonId	GET /agr/expression/{taxonId}
AgrPhenotypes::getPhenotypesForTaxonUsingGet()	Get phenotype annotations submitted by RGD to AGR by taxonId	GET /agr/phenotypes/{taxonId}
AgrVariants::getVariantsForTaxonUsingGet()	Get basic variant records submitted by RGD to AGR by taxonId	GET /agr/variants/{taxonId}
Annotations::getAnnotationsUsingPost()	Return a list of genes annotated to an ontology term	POST /annotations/
Annotations::getAnnotationsByAccIdAndRgdIdUsingGet()	Returns a list of annotations by RGD ID and ontology term accession ID	GET /annotations/{accId}/{rgdId}
Annotations::getAnnotationsUsingGet()	Returns a list annotations for an ontology term or a term and it’s children	GET /annotations/{accId}/{speciesTypeKey}/{includeChildren}
AnnotationsAccId::getTermAccIdsUsingGet()	Returns a list ontology term accession IDs annotated to an rgd object	GET /annotations/accId/{rgdId}
AnnotationsCount::getAnnotationCountByAccIdUsingGet()	Returns annotation count for ontology accession ID	GET /annotations/count/{accId}/{includeChildren}
AnnotationsCount::getAnnotationCountByAccIdAndSpeciesUsingGet()	Returns annotation count for ontology accession ID and speicies	GET /annotations/count/{accId}/{speciesTypeKey}/{includeChildren}
AnnotationsCount::getAnnotationCountByAccIdAndObjectTypeUsingGet()	Returns annotation count for ontology accession ID and object type	GET /annotations/count/{accId}/{speciesTypeKey}/{includeChildren}/{objectType}
AnnotationsReference::getAnnotsByRefrerenceUsingGet()	Returns a list of annotations for a reference	GET /annotations/reference/{refRgdId}
AnnotationsRgdId::getAnnotationsByRgdIdUsingGet()	Returns a list of annotations by RGD ID	GET /annotations/rgdId/{rgdId}
AnnotationsRgdId::getAnnotationsByRgdIdAndOntologyUsingGet()	Returns a list of annotations by RGD ID and ontology prefix	GET /annotations/rgdId/{rgdId}/{ontologyPrefix}
EnrichmentAnnotatedGenes::getEnrichmentDataUsingPost()	Return a list of genes annotated to the term.Genes are rgdids separated by comma.Species type is an integer value.term is the ontology	POST /enrichment/annotatedGenes
EnrichmentData::getEnrichmentDataUsingPost1()	Return a chart of ontology terms annotated to the genes.Genes are rgdids separated by comma.Species type is an integer value.Aspect is the Ontology group	POST /enrichment/data
Genes::getGenesByPositionUsingGet()	Return a list of genes position and map key	GET /genes/{chr}/{start}/{stop}/{mapKey}
Genes::getGeneByRgdIdUsingGet()	Get a gene record by RGD ID	GET /genes/{rgdId}
Genes::getGeneBySymbolUsingGet()	Get a gene record by symbol and species type key	GET /genes/{symbol}/{speciesTypeKey}
GenesAffyId::getGenesByAffyIdUsingGet()	Return a list of genes for an affymetrix ID	GET /genes/affyId/{affyId}/{speciesTypeKey}
GenesAlias::getGenesByAliasSymbolUsingGet()	Return a list of genes for an alias and species	GET /genes/alias/{aliasSymbol}/{speciesTypeKey}
GenesAllele::getGeneAllelesUsingGet()	Return a list of gene alleles	GET /genes/allele/{rgdId}
GenesAnnotation::getAnnotatedGenesUsingPost()	Return a list of genes annotated to an ontology term	POST /genes/annotation
GenesAnnotation::getAllAnnotatedGenesUsingGet()	Return a list of genes annotated to an ontology term	GET /genes/annotation/{accId}
GenesAnnotation::getGenesAnnotatedUsingGet()	Return a list of genes annotated to an ontology term	GET /genes/annotation/{accId}/{speciesTypeKey}
GenesKeyword::getGenesByKeywordUsingGet()	Return a list of genes by keyword and species type key	GET /genes/keyword/{keyword}/{speciesTypeKey}
GenesMap::getGeneByMapKeyUsingGet()	Return a list of all genes with position information for an assembly	GET /genes/map/{mapKey}
GenesMapped::getMappedGenesByPositionUsingGet()	Return a list of genes position and map key	GET /genes/mapped/{chr}/{start}/{stop}/{mapKey}
GenesOrthologs::getOrthologsByListUsingPost()	Return a list of gene orthologs	POST /genes/orthologs
GenesOrthologs::getGeneOrthologsUsingGet()	Return a list of gene orthologs	GET /genes/orthologs/{rgdId}
GenesRegion::getGenesInRegionUsingGet()	Return a list of genes in region	GET /genes/region/{chr}/{start}/{stop}/{mapKey}
GenesSpecies::getGenesBySpeciesUsingGet()	Return a list of all genes for a species in RGD	GET /genes/species/{speciesTypeKey}
LookupGeneTypes::getGeneTypesUsingGet()	Returns a list of gene types avialable in RGD	GET /lookup/geneTypes
LookupIdMapEnsemblGene::getEnsemblGeneMappingUsingPost()	Translate RGD IDs to Ensembl Gene IDs	POST /lookup/id/map/EnsemblGene
LookupIdMapEnsemblGene::getEnsemblGeneMappingUsingGet()	Translate an RGD ID to an Ensembl Gene ID	GET /lookup/id/map/EnsemblGene/{rgdId}
LookupIdMapEnsemblProtein::getEnsemblProteinMappingUsingPost()	Translate RGD IDs to Ensembl Protein IDs	POST /lookup/id/map/EnsemblProtein
LookupIdMapEnsemblProtein::getEnsemblProteinMappingUsingGet()	Translate an RGD ID to an Ensembl Protein ID	GET /lookup/id/map/EnsemblProtein/{rgdId}
LookupIdMapEnsemblTranscript::getEnsemblTranscriptMappingUsingPost()	Translate RGD IDs to Ensembl Transcript IDs	POST /lookup/id/map/EnsemblTranscript
LookupIdMapEnsemblTranscript::getEnsemblTranscriptMappingUsingGet()	Translate an RGD ID to an Ensembl Transcript ID	GET /lookup/id/map/EnsemblTranscript/{rgdId}
LookupIdMapGenBankNucleotide::getGenBankNucleotideMappingUsingPost()	Translate RGD IDs to GenBank Nucleotide IDs	POST /lookup/id/map/GenBankNucleotide
LookupIdMapGenBankNucleotide::getGenBankNucleotideMappingUsingGet()	Translate an RGD ID to a GenBank Nucleotide ID	GET /lookup/id/map/GenBankNucleotide/{rgdId}
LookupIdMapGenBankProtein::getGenBankProteinMappingUsingPost()	Translate RGD IDs to GenBank Protein IDs	POST /lookup/id/map/GenBankProtein
LookupIdMapGenBankProtein::getGenBankProteinMappingUsingGet()	Translate an RGD ID to a GenBank Protein ID	GET /lookup/id/map/GenBankProtein/{rgdId}
LookupIdMapGtex::getGtexmappingUsingPost()	Translate RGD IDs to GTEx IDs	POST /lookup/id/map/GTEx
LookupIdMapGtex::getGtexmappingUsingGet()	Translate an RGD ID to an GTEx ID	GET /lookup/id/map/GTEx/{rgdId}
LookupIdMapHgnc::getHgncmappingUsingPost()	Translate RGD IDs to HGNC IDs	POST /lookup/id/map/HGNC
LookupIdMapHgnc::getHgncmappingUsingGet()	Translate an RGD ID to an HGNC ID	GET /lookup/id/map/HGNC/{rgdId}
LookupIdMapMgi::getMgimappingUsingPost()	Translate RGD IDs to MGI IDs	POST /lookup/id/map/MGI
LookupIdMapMgi::getMgimappingUsingGet()	Translate an RGD ID to an MGI ID	GET /lookup/id/map/MGI/{rgdId}
LookupIdMapNcbigene::getNcbigeneMappingUsingPost()	Translate RGD IDs to NCBI Gene IDs	POST /lookup/id/map/NCBIGene
LookupIdMapNcbigene::getNcbigeneMappingUsingGet()	Translate an RGD ID to an NCBI Gene ID	GET /lookup/id/map/NCBIGene/{rgdId}
LookupIdMapUniProt::getUniProtMappingUsingPost()	Translate RGD IDs to UniProt IDs	POST /lookup/id/map/UniProt
LookupIdMapUniProt::getUniProtMappingUsingGet()	Translate an RGD ID to a UniProt ID	GET /lookup/id/map/UniProt/{rgdId}
LookupMaps::getMapsUsingGet()	Return a list assembly maps for a species	GET /lookup/maps/{speciesTypeKey}
LookupSpeciesTypeKeys::getSpeciesTypesUsingGet()	Return a Map of species type keys available in RGD	GET /lookup/speciesTypeKeys
LookupStandardUnit::getMapsUsingGet1()	Return a standardUnit for an ontology if it exists	GET /lookup/standardUnit/{accId}
Maps::getMapsBySpeciesUsingGet()	Return a list of assemblies	GET /maps/{speciesTypeKey}
MapsChr::getChromosomeByAssemblyUsingGet()	Return a list of chromosomes	GET /maps/chr/{chromosome}/{mapKey}
MapsChr::getChromosomesByAssemblyUsingGet()	Return a list of chromosomes	GET /maps/chr/{mapKey}
OntologyOnt::getOntDagsUsingGet()	Returns child and parent terms for Accession ID	GET /ontology/ont/{accId}
OntologyTerm::isDescendantOfUsingGet()	Returns true or false for terms	GET /ontology/term/{accId1}/{accId2}
OntologyTerm::getTermUsingGet()	Returns term for Accession ID	GET /ontology/term/{accId}
PathwaysDiagramsForCategory::getPathwaysWithDiagramsForCategoryUsingGet()	Return a list of pathways based on category provided	GET /pathways/diagramsForCategory/{category}
PathwaysDiagramsSearch::pathwaysUsingGet()	Return a list of pathways based on search term	GET /pathways/diagrams/search/{searchString}
PhenotypePhenominerChart::getChartInfoUsingGet()	Return a list of quantitative phenotypes values based on a combination of Clinical Measurement, Experimental Condition, Rat Strain, and/or Measurement Method ontology terms. Results will be all records that match all terms submitted. Ontology ids should be submitted as a comma delimited list (ex. RS:0000029,CMO:0000155,CMO:0000139). Species type is an integer value (3=rat, 4=chinchilla). Reference RGD ID for a study works like a filter.	GET /phenotype/phenominer/chart/{speciesTypeKey}/{refRgdId}/{termString}
PhenotypePhenominerChart::getChartInfoUsingGet1()	Return a list of quantitative phenotypes values based on a combination of Clinical Measurement, Experimental Condition, Rat Strain, and/or Measurement Method ontology terms. Results will be all records that match all terms submitted. Ontology ids should be submitted as a comma delimited list (ex. RS:0000029,CMO:0000155,CMO:0000139). Species type is an integer value (3=rat, 4=chinchilla)	GET /phenotype/phenominer/chart/{speciesTypeKey}/{termString}
Qtls::getQtlListByPositionUsingGet()	Returns a list QTL for given position and assembly map	GET /qtls/{chr}/{start}/{stop}/{mapKey}
Qtls::getQtlbyRgdIdUsingGet()	Return a QTL for provided RGD ID	GET /qtls/{rgdId}
QtlsMapped::getMappedQtlbyPositionUsingGet()	Returns a list QTL for given position and assembly map	GET /qtls/mapped/{chr}/{start}/{stop}/{mapKey}
SslpsMapped::getMappedSslpbyPositionUsingGet()	Returns a list SSLP for given position and assembly map	GET /sslps/mapped/{chr}/{start}/{stop}/{mapKey}
StatsCountActiveObject::getActiveObjectCountUsingGet()	Count of active objects by type, for specified species and date	GET /stats/count/activeObject/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountGeneType::getGeneTypeCountUsingGet()	Count of gene types, for specified species and date	GET /stats/count/geneType/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountObjectStatus::getObjectStatusCountUsingGet()	Count of objects with given status, for specified species and date	GET /stats/count/objectStatus/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountObjectWithRefSeq::getObjectsWithRefSeqCountUsingGet()	Count of objects with reference sequence(s), by object type, for specified species and date	GET /stats/count/objectWithRefSeq/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountObjectWithReference::getObjectsWithReferenceCountUsingGet()	Count of objects with reference, by object type, for specified species and date	GET /stats/count/objectWithReference/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountObjectWithXdb::getObjectsWithXdbsCountUsingGet()	Count of objects with external database ids, by database id, for specified species, object type and date	GET /stats/count/objectWithXdb/{speciesTypeKey}/{objectKey}/{dateYYYYMMDD}
StatsCountProteinInteraction::getProteinInteractionCountUsingGet()	Count of protein interactions, for specified species and date	GET /stats/count/proteinInteraction/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountQtlInheritanceType::getQtlInheritanceTypeCountUsingGet()	Count of strains, by qtl inheritance type, for specified species and date	GET /stats/count/qtlInheritanceType/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountRetiredObject::getRetiredObjectCountUsingGet()	Count of retired objects by type, for specified species and date	GET /stats/count/retiredObject/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountStrainType::getStrainTypeCountUsingGet()	Count of strain types, for specified species and date	GET /stats/count/strainType/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountWithdrawnObject::getWithdrawnObjectCountUsingGet()	Count of withdrawn objects by type, for specified species and date	GET /stats/count/withdrawnObject/{speciesTypeKey}/{dateYYYYMMDD}
StatsCountXdb::getXdbsCountUsingGet()	Count of external database ids, for specied species and date	GET /stats/count/xdb/{speciesTypeKey}/{dateYYYYMMDD}
StatsDiffActiveObject::getActiveObjectDiffUsingGet()	Count difference of active objects, by type, for specified species and date range	GET /stats/diff/activeObject/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffGeneType::getGeneTypeDiffUsingGet()	Count difference of gene types, for specified species and date range	GET /stats/diff/geneType/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffObjectStatus::getObjectStatusDiffUsingGet()	Count difference of objects with given status, for specified species and date range	GET /stats/diff/objectStatus/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffObjectWithRefSeq::getObjectsWithRefSeqDiffUsingGet()	Count difference of objects with reference sequence(s), by object type, for specified species and date range	GET /stats/diff/objectWithRefSeq/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffObjectWithReference::getObjectsWithReferenceDiffUsingGet()	Count difference of objects with reference, by object type, for specified species and date range	GET /stats/diff/objectWithReference/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffObjectWithXdb::getObjectsWithXdbsDiffUsingGet()	Count difference of objects with external database ids, by database id, for specified species, object type and date range	GET /stats/diff/objectWithXdb/{speciesTypeKey}/{objectKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffProteinInteraction::getProteinInteractionDiffUsingGet()	Count difference of protein interactions, for specified species and date range	GET /stats/diff/proteinInteraction/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffQtlInheritanceType::getQtlInheritanceTypeDiffUsingGet()	Count difference of strains, by qtl inheritance type, for specified species and date range	GET /stats/diff/qtlInheritanceType/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffRetiredObject::getRetiredObjectDiffUsingGet()	Count difference of retired objects, by type, for specified species and date range	GET /stats/diff/retiredObject/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffStrainType::getStrainTypeDiffUsingGet()	Count difference of strain types, for specified species and date range	GET /stats/diff/strainType/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffWithdrawnObject::getWithdrawnObjectDiffUsingGet()	Count difference of withdrawn objects, by type, for specified species and date range	GET /stats/diff/withdrawnObject/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsDiffXdb::getXdbsDiffUsingGet()	Count difference of external database ids, for specified species and date range	GET /stats/diff/xdb/{speciesTypeKey}/{dateFromYYYYMMDD}/{dateToYYYYMMDD}
StatsTerm::getTermStatsUsingGet()	getTermStats	GET /stats/term/{accId}/{filterAccId}
Strains::getStrainsByPositionUsingGet()	Return all active strains by position	GET /strains/{chr}/{start}/{stop}/{mapKey}
Strains::getStrainByRgdIdUsingGet()	Return a strain by RGD ID	GET /strains/{rgdId}
StrainsAll::getAllStrainsUsingGet()	Return all active strains in RGD	GET /strains/all

Making a Request¶

There are two ways to make a request to the nominated API Handler and API Method:

If you built the client to be accessible globally, you can use the relevant API Handler Class directly:

use Tectalic\RatGenomeDatabase\Handlers\Agr;
 
(new Agr())->getGenesForLatestAssemblyUsingGet();

Alternatively, you can access all API Handlers from the client class using the Client class:

$client->agr()->getGenesForLatestAssemblyUsingGet();

Retrieving the Response¶

Once you have made a request using one of the two methods outlined above, the next step is to access the response.

You can access the response in different ways. Please choose your preferred one.

Model Responses¶

Model responses are Data Transfer Object (DTO) style PHP classes, with public properties for each API property.

They offer a structured way of retrieving the response from an API request.

All Response Models are an instance of \Spatie\DataTransferObject\DataTransferObject or \Spatie\DataTransferObject\DataTransferObjectCollection.

After performing the request, use the ->toModel() fluent method to the API Method:

use Tectalic\RatGenomeDatabase\Handlers\Agr;
 
$model = (new Agr())->getGenesForLatestAssemblyUsingGet()->toModel();

Each API Method’s toModel() call will return the appropriate Model class type for the API Method you have just called.

Associative Array Responses¶

After performing the request, use the ->toArray() fluent method to the API Method:

use Tectalic\RatGenomeDatabase\Handlers\Agr;
 
$array = (new Agr())->getGenesForLatestAssemblyUsingGet()->toArray();

In the resulting associative array, the array keys will match the names of the public properties in the relevant Model class.

PSR 7 Response Objects¶

If you need to access the raw response or inspect the HTTP headers, use the ->getResponse() fluent method to the API Method. It will return a Psr\Http\Message\ResponseInterface:

use Tectalic\RatGenomeDatabase\Handlers\Agr;
 
$response = (new Agr())->getGenesForLatestAssemblyUsingGet()->getResponse();

Errors¶

When performing requests with Tectalic Rat Genome Database REST API Client, specific scenarios will cause a Tectalic\RatGenomeDatabase\Exception\ClientException to be thrown. Please see below for details.

Invalid Usage of the Manager Class¶

A \LogicException will be thrown if the Manager::build() function is called multiple times, or if Manager::access() is called before calling Manager::build().

Unsuccessful HTTP Response Codes¶

The Tectalic Rat Genome Database REST API Client depends on a PSR-18 compatible HTTP client, and that HTTP client should not throw an exception for unsuccessful HTTP response codes.

An unsuccessful response code is classified as one that is not in the range 200-299 (inclusive). Examples of unsuccessful response codes include:

• Informational responses (100-199)
• Redirection responses (300-399)
• Client error responses (400-499)
• Server error responses (500-599)

If an unsuccessful response code does occur:

• your HTTP Client will not throw an Exception.
• the API Handler’s toModel() method will throw a ClientException.
• the API Handler’s toArray() method will return the response body and not throw a ClientException.
• The API Handler’s getResponse() method will return the raw response and not throw a ClientException.

Below is an example of how you may wish to use a try/catch block when performing a request so that you can detect and handle unexpected errors.

use Tectalic\RatGenomeDatabase\Client;
use Tectalic\RatGenomeDatabase\ClientException;
use Tectalic\RatGenomeDatabase\Manager;
 
// Build a Tectalic Rat Genome Database REST API Client globally.
 
Manager::build($httpClient, $auth);
$handler = new Agr();
 
// Perform a request
try {
    $model = $handler->getGenesForLatestAssemblyUsingGet()->toModel();
    // Do something with the response model...
} catch (ClientException $e) {
    // Error response received. Retrieve the HTTP response code and response body.
    $responseBody = $handler->toArray();
    $rawResponse  = $handler->getResponse()->getResponse();
    $responseCode = $handler->getResponse()->getStatusCode();
    // Handle the error...
}

HTTP Client Exceptions¶

If your HTTP client of choice throws an exception other than ClientException, the Tectalic Rat Genome Database REST API Client Client and its API Handler classes will let these exceptions bubble up.

Consult your HTTP client’s documentation for more details on exception handling.

Tests¶

The Tectalic Rat Genome Database REST API Client package includes several types of automated PHPUnit tests to verify the correct operation:

• Unit Tests
• Integration Tests

To run these tests, you will need to have installed the Tectalic Rat Genome Database REST API Client package with its dev dependencies (i.e. not using the --no-dev flag when running composer).

Unit Tests¶

These PHPUnit tests are designed to:

• confirm that each API Method assembles a valid request that matches the Rat Genome Database API OpenAPI specification.
• verify the behaviour of other parts of the package, such as the Client and Manager classes.

The unit tests can be run using the following command, which needs to be run from this package’s root directory.

composer test:unit

Unit tests do not perform any real requests against the Rat Genome Database API.

Unit tests are located in the tests/Unit directory.

Integration Tests¶

Integration tests are located in the tests/Integration directory.

These PHPUnit tests are designed to confirm that each API Method parses a valid response, according to the Rat Genome Database API OpenAPI specification. Out of the box the integration tests are designed to work with the Prism Mock Server.

Using Prism as the Target¶

Make sure Prism is installed. Please see the Prism documentation for details on how to install Prism.

Once Prism is installed, you can run prism and the integration tests side by side in separate terminal windows, or using the following command, which need to be run from this package’s root directory.

echo "> Starting Prism server"
prism mock tests/openapi.json >/dev/null 2>&1 &
PRISM_PID=$!
sleep 2
echo "  => Started"
composer test:integration
kill $PRISM_PID

Those commands will start the Prism mock server, then run the integration tests, and then stop the Prism mock server when the tests are completed.

In this case the integration tests do not perform any real requests against the Rat Genome Database API.

Using a Different Target¶

By setting the RAT_GENOME_DATABASE_CLIENT_TEST_BASE_URI environment variable, you can set a different API endpoint target for the integration tests.

For example, instead of using Prism, you can use a different mocking/staging/test server of your choice, or you can use the Rat Genome Database API’s live endpoints.

After your setup is complete simply run the following command.

composer test:integration

We do not recommend running integration tests against the live Rat Genome Database API endpoints. This is because the tests will send example data to all endpoints, which can result in new data being created, or existing data being deleted.

Support¶

If you have any questions or feedback, you can submit a support request to the Tectalic developers by going to https://tectalic.com/support/rat-genome-database.

License¶

This software is copyright (c) Tectalic.

For the full copyright and license information, please view the ‘LICENSE’ file distributed with the source code.