libapi

This library provides client side service wrappers to access identifiers.org Cloud based API

License

License

Categories

Categories

IDE Development Tools
GroupId

GroupId

org.identifiers.cloud
ArtifactId

ArtifactId

libapi
Last Version

Last Version

2.3.0
Release Date

Release Date

Type

Type

jar
Description

Description

libapi
This library provides client side service wrappers to access identifiers.org Cloud based API
Project URL

Project URL

http://identifiers.org
Project Organization

Project Organization

The European Bioinformatics Institute
Source Code Management

Source Code Management

https://github.com/identifiers-org/cloud-libapi/tree/master

Download libapi

How to add to project

<!-- https://jarcasting.com/artifacts/org.identifiers.cloud/libapi/ -->
<dependency>
    <groupId>org.identifiers.cloud</groupId>
    <artifactId>libapi</artifactId>
    <version>2.3.0</version>
</dependency>
// https://jarcasting.com/artifacts/org.identifiers.cloud/libapi/
implementation 'org.identifiers.cloud:libapi:2.3.0'
// https://jarcasting.com/artifacts/org.identifiers.cloud/libapi/
implementation ("org.identifiers.cloud:libapi:2.3.0")
'org.identifiers.cloud:libapi:jar:2.3.0'
<dependency org="org.identifiers.cloud" name="libapi" rev="2.3.0">
  <artifact name="libapi" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.identifiers.cloud', module='libapi', version='2.3.0')
)
libraryDependencies += "org.identifiers.cloud" % "libapi" % "2.3.0"
[org.identifiers.cloud/libapi "2.3.0"]

Dependencies

compile (15)

Group / Artifact Type Version
com.fasterxml.jackson.core : jackson-annotations jar 2.9.8
com.fasterxml.jackson.core : jackson-databind jar 2.9.8
com.fasterxml.jackson.dataformat : jackson-dataformat-yaml jar 2.9.8
org.springframework : spring-web jar 5.1.5.RELEASE
org.slf4j : slf4j-api jar 1.7.26
org.slf4j : jul-to-slf4j jar 1.7.26
org.slf4j : jcl-over-slf4j jar 1.7.26
ch.qos.logback : logback-core jar 1.2.3
ch.qos.logback : logback-classic jar 1.2.3
org.springframework.retry : spring-retry jar 1.2.4.RELEASE
junit : junit jar 4.12
org.hamcrest : hamcrest-library jar 1.3
org.hamcrest : hamcrest-core jar 1.3
org.mockito : mockito-core jar 2.25.1
net.jcip : jcip-annotations jar 1.0

provided (1)

Group / Artifact Type Version
org.projectlombok : lombok jar 1.18.6

Project Modules

There are no modules declared in this project.

Overview

This is a Java library that implements clients for identifiers.org Web Services.

The following sections will explain how to use the different service wrappers to access identifiers.org Web Services on any of its cloud deployments.

How to link this library in your code

This library is available at Maven Central, you can use it by just adding the following dependency:

Maven

<dependency>
    <groupId>org.identifiers.cloud</groupId>
    <artifactId>libapi</artifactId>
    <version>1.1.0</version>
</dependency>

Apache Buildr

'org.identifiers.cloud:libapi:jar:1.1.0'

Apache Ivy

<dependency org="org.identifiers.cloud" name="libapi" rev="1.1.0" />

Groovy Grape

@Grapes(
@Grab(group='org.identifiers.cloud', module='libapi', version='1.1.0')
)

Gradle/Grails

compile 'org.identifiers.cloud:libapi:1.1.0'

Scala SBT

libraryDependencies += "org.identifiers.cloud" % "libapi" % "1.1.0"

Leiningen

[org.identifiers.cloud/libapi "1.1.0"]

Using to identifiers.org API Web Services

Compact ID Resolution Service

The following code snippet shows how to get an instance of the service wrapper for identifiers.org Resolver Service, and query the service for a given Compact ID.

import org.identifiers.cloud.libapi.services.ApiServicesFactory;
import org.identifiers.cloud.libapi.models.resolver.ServiceResponseResolve;

// For accessing a locally deployed Resolver service at 'localhost:8080', and requesting resolution of
// Compact ID 'CHEBI:36927'
ServiceResponseResolve response = ApiServicesFactory
                .getResolverService("localhost", "8080")
                .requestCompactIdResolution("CHEBI:36927");

// For accessing a locally deployed Resolver service at 'localhost:8080', and requesting resolution of
// Compact ID 'CHEBI:36927', but constraining the resource provider to 'ebi'
ServiceResponseResolve response = ApiServicesFactory
                .getResolverService("localhost", "8080")
                .requestCompactIdResolution("CHEBI:36927", "ebi");

Additional factory methods are available where only the service 'host' is specified, in that case port '80' will be used, or where no 'host' or 'port' information is given, so the factory will provide an instance of the service client pointing to any of the identifiers.org cloud deployments.

Metadata Service

The following code snippet shows how to get an instance of the service wrapper for identifiers.org Metadata Service, and submit metadata requests.

import org.identifiers.cloud.libapi.services.ApiServicesFactory;
import org.identifiers.cloud.libapi.models.metadata.ServiceResponseFetchMetadata;
import org.identifiers.cloud.libapi.models.metadata.ServiceResponseFetchMetadataForUrl;

// Requesting metadata for a given Compact ID, the Metadata Service will choose the resource provider with the highest
// recommendation index / score.
ServiceResponseFetchMetadata response = ApiServicesFactory
                .getMetadataService("localhost", "8082")
                .getMetadataForCompactId("CHEBI:36927");

// Requesting metadata for a given URL.
ServiceResponseFetchMetadataForUrl response = ApiServicesFactory
                .getMetadataService("localhost", "8082")
                .getMetadataForUrl("http://reactome.org/content/detail/R-HSA-201451");

Additional factory methods are available where only the service 'host' is specified, in that case port '80' will be used, or where no 'host' or 'port' information is given, so the factory will provide an instance of the service client pointing to any of the identifiers.org cloud deployments.

Registry Service

The following code snippet shows how to get an instance of the service wrapper for identifiers.org Registry Service, and submit registration or validation requests.

import org.identifiers.cloud.libapi.models.registry.Requester;
import org.identifiers.cloud.libapi.models.registry.requests.prefixregistration.ServiceRequestRegisterPrefixPayload;
import org.identifiers.cloud.libapi.models.registry.responses.prefixregistration.ServiceResponseRegisterPrefix;
import org.identifiers.cloud.libapi.models.registry.responses.validation.ServiceResponseValidateRequest;


// Preparing a prefix registration request payload
ServiceRequestRegisterPrefixPayload payload =
            new ServiceRequestRegisterPrefixPayload()
                                    .setName("A Name for this prefix Registration Request")
                                    .setDescription("This is a sample prefix registration request from a unit test of libapi, " +
                                            "we need enouch characters for the description")
                                    .setHomePage("http://your_home.page")
                                    .setOrganization("Your Organization")
                                    .setPreferredPrefix("mynewprefix")
                                    .setResourceAccessRule("http://whatever_url/{$id}")
                                    .setExampleIdentifier("a_sample_id")
                                    .setRegexPattern("\\d+")
                                    .setReferences(new String[]{"ref1", "ref2"})
                                    .setAdditionalInformation("Additional information about this unit test")
                                    .setRequester(new Requester()
                                            .setEmail("requester@your_organization.mail")
                                            .setName("Requester Full Name"));

// Prefix registration request
ServiceResponseRegisterPrefix response =
                ApiServicesFactory.getRegistryService("localhost", "8081")
                        .requestPrefixRegistration(payload);

// There are methods for individual validation of the prefix registration payload fields, they all use the same
// 'ServiceRequestRegisterPrefixPayload' payload object, filled only with the field that wants to be validated. As an
// example, the following lines of code will validate the 'name' field.
// Fill in the payload with just the 'name' field
ServiceRequestRegisterPrefixPayload payload =
            new ServiceRequestRegisterPrefixPayload()
                                    .setName("A Name for this prefix Registration Request");
// Request validation
ServiceResponseValidateRequest response =
                ApiServicesFactory.getRegistryService("localhost", "8081")
                        .requestValidationName(payload);

Additional factory methods are available where only the service 'host' is specified, in that case port '80' will be used, or where no 'host' or 'port' information is given, so the factory will provide an instance of the service client pointing to any of the identifiers.org cloud deployments.

Resolution Data Insight API

It is possible to get 'insights' into currently available resolution data through this API.

The currently supported use cases are shown below this line.

// To get sample URLs to all the resource providers available in the resolution service, the following call can be used
ServiceResponseResolve response = ApiServicesFactory
        .getResolverService("localhost", "8080")
        .getAllSampleIdsResolved();

// To get a home URL for all the resource providers available in the resolution service, the following call can be used
ServiceResponseResolve response = ApiServicesFactory
        .getResolverService("localhost", "8080")
        .getAllHomeUrls();

Responses from the services

The responses from the different services will provide information on how the request was completed, via HTTP Status code and a possible error message, as well as a specialized payload for the particular request submitted.

For further details, please refer to the javadoc accompanying this library.

Library Configuration

This library is able to provide clients for the different clouds where identifiers.org has deployed its services, i.e. Amazon Web Services, Google Cloud or Microsoft Azure. By default, a deployment is chosen randomly between all the possible ones every time a web service client is requested, but this behaviour can be modified for those use cases where we would like to lock in a cloud provider, i.e. we would like to use identifiers.org web services that are part of only one cloud deployment, this can be done using a deployment selector within the library configuration as shown in the following code snippet.

import org.identifiers.cloud.libapi.Configuration;

// This call we'll make the library always select identifiers.org AWS deployment
Configuration.selectDeployment(Configuration.InfrastructureDeploymentSelector.AWS);

// To make the library select random deployments again (default behaviour), we use the 'ANY' selector
Configuration.selectDeployment(Configuration.InfrastructureDeploymentSelector.ANY);

Please, take into account that all code samples provided, were pointing to local deployments of identifiers.org, and it is advised to let the library configuration manager to either choose a random deployment, or lock it down to a particular cloud, so no information regarding host (e.g. 'localhost' in the examples) and port (e.g. 8080 in the case of the resolution code snippet) is needed.

Contact

Manuel Bernal Llinares

org.identifiers.cloud

Idenfitiers.org

Identifiers for the Life Sciences World

Versions

Version
2.3.0
2.2.0
2.0.0
1.1.1
1.1.0
1.0.2
1.0.1
1.0.0