README.md 9.21 KB
Newer Older
1
2
# Java client for the Global Information System for PGRFA

Matija Obreza's avatar
Matija Obreza committed
3
The GLIS test environment is accessible at <https://glistest.planttreaty.org/>
4

5
6
7
8
9
10
11
# Using the Java library

We provide different flavors of the library (with different dependencies):

- **[glis-client-okhttp-gson](okhttp-gson)**
- **[glis-client-jersey2](jersey2)**
- **[glis-client-resttemplate](resttemplate)** using Spring REST Template
12
- [glis-client-resteasy](resteasy) (needs testing)
Matija Obreza's avatar
Matija Obreza committed
13
- [glis-client-csharp](csharp) (needs .Net contributors)
14

Matija Obreza's avatar
Matija Obreza committed
15
## Maven users
16

17
18
19
20
21
22
23
24
25
26
27
28
### OK HTTP + GSON

```xml
<dependency>
    <groupId>org.genesys-pgr</groupId>
    <artifactId>glis-client-okhttp-gson</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>
```

### Jersey2
29

Matija Obreza's avatar
Matija Obreza committed
30
31
32
```xml
<dependency>
    <groupId>org.genesys-pgr</groupId>
33
34
35
36
37
38
39
40
41
42
43
44
    <artifactId>glis-client-jersey2</artifactId>
    <version>1.0-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>
```

### Spring REST template

```xml
<dependency>
    <groupId>org.genesys-pgr</groupId>
    <artifactId>glis-client-resttemplate</artifactId>
Matija Obreza's avatar
Matija Obreza committed
45
46
47
48
49
50
51
52
53
54
    <version>1.0-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>
```

## Gradle users

Add this dependency to your project's build file:

```groovy
55
compile "org.genesys-pgr:glis-client-okhttp-gson:1.0-SNAPSHOT"
Matija Obreza's avatar
Matija Obreza committed
56
```
57

58
59
... and similar for other flavors.

60
61
62
63
64
65
## Test and Production GLIS environment

To change the base URL of the GLIS api server (i.e. switch between production and testing environments) you must change the `ApiClient` setting:

```java
ApiClient client = // ...
66
client.setBasePath("https://glis.planttreaty.org")
67
68
69
70
71
72
```

This can be done either on the `Configuration.getDefaultApiClient()` singleton object:

```java
ApiClient defaultClient = Configuration.getDefaultApiClient();
73
defaultClient.setBasePath("https://glis.planttreaty.org")
74
75
76
77
78
```

... or when creating a new API instance:

```java
79
ApiClient client = new ApiClient();
80
client.setBasePath("https://glis.planttreaty.org");
Matija Obreza's avatar
Matija Obreza committed
81
QueryApi api = new QueryApi(client);
82
83
```

Matija Obreza's avatar
Matija Obreza committed
84
85
86
87
88
89
90
91
## Getting Started

Please follow the [installation](#installation) instruction and execute the following Java code:

```java
import org.genesys.glis.v1.invoker.*;
import org.genesys.glis.v1.invoker.auth.*;
import org.genesys.glis.v1.model.*;
Matija Obreza's avatar
Matija Obreza committed
92
import org.genesys.glis.v1.api.QueryApi;
Matija Obreza's avatar
Matija Obreza committed
93
94
95
96

import java.io.File;
import java.util.*;

97
public class QueryApiExample {
Matija Obreza's avatar
Matija Obreza committed
98
99
100
101

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

102
        // Optionally configure HTTP basic authorization: easySmta
Matija Obreza's avatar
Matija Obreza committed
103
104
105
106
        HttpBasicAuth easySmta = (HttpBasicAuth) defaultClient.getAuthentication("easySmta");
        easySmta.setUsername("YOUR USERNAME");
        easySmta.setPassword("YOUR PASSWORD");

Matija Obreza's avatar
Matija Obreza committed
107
        QueryApi apiInstance = new QueryApi();
Matija Obreza's avatar
Matija Obreza committed
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
        Integer page = 1; // Integer | Request a particular page
        Integer perPage = 10; // Integer | The number of items returned in a single page
        String doi = "doi_example"; // String | Digital Object Identifier (DOI) associated to the PGRFA
        String identifier = "identifier_example"; // String | Any identifier associated with the PGRFA, excluding the DOI
        String genus = "genus_example"; // String | Genus of the PGRFA
        String species = "species_example"; // String | Species and other taxonomic elements
        String name = "name_example"; // String | Any name associated with the PGRFA
        String holdwiews = "holdwiews_example"; // String | FAO/WIEWS Institute code of the holding institution
        String holdpid = "holdpid_example"; // String | Easy-SMTA PID of the holding institution or person
        String holdname = "holdname_example"; // String | Name and surname for persons or Organization name of the holding institution or person
        String holdcountry = "holdcountry_example"; // String | ISO-3166 alpha-3 country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the holding institution or person
        String methodcode = "methodcode_example"; // String | Code of the method through which the PGRFA has been acquired. See Table 1 for the codes accepted by this element. TODO enum
        String provwiews = "provwiews_example"; // String | FAO/WIEWS Institute code of the providing institution
        String provpid = "provpid_example"; // String | Easy-SMTA PID of the providing institution or person
        String provname = "provname_example"; // String | Name and surname for persons or Organization name of the providing institution
        String provcountry = "provcountry_example"; // String | ISO-3166 alpha-3 country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the providing institution or person
        String provenance = "provenance_example"; // String | ISO-3166 alpha-3 country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the providing institution or person
        String collwiews = "collwiews_example"; // String | FAO/WIEWS Institute code of the collecting institution
        String collpid = "collpid_example"; // String | Easy-SMTA PID of the collecting institution or person
        String collname = "collname_example"; // String | Name and surname for persons or Organization name of the collecting institution or person
        String collcountry = "collcountry_example"; // String | ISO-3166 alpha-3 country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the collecting institution or person
        String bredwiews = "bredwiews_example"; // String | FAO/WIEWS Institute code of the breeding institution
        String bredpid = "bredpid_example"; // String | Easy-SMTA PID of the breeding institution or person
        String bredname = "bredname_example"; // String | Name and surname for persons or Organization name of the breeding institution or person
        String bredcountry = "bredcountry_example"; // String | ISO-3166 alpha-3 country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) of the breeding institution or person
        String biostatus = "biostatus_example"; // String | Code of the biological status of sample (MCPD SAMPSTAT).
        String mlsstatus = "mlsstatus_example"; // String | Code for the inclusion into the Multilateral System.
        String targetkw = "targetkw_example"; // String | Code for the keyword for a target associated to the PGRFA. To obtain the list of keyword codes, please see \"Controlled vocabulary query\".
        try {
            List<PGRFA> result = apiInstance.search(page, perPage, doi, identifier, genus, species, name, holdwiews, holdpid, holdname, holdcountry, methodcode, provwiews, provpid, provname, provcountry, provenance, collwiews, collpid, collname, collcountry, bredwiews, bredpid, bredname, bredcountry, biostatus, mlsstatus, targetkw);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling PgrfaApi#search");
            e.printStackTrace();
        }
    }
}
```

## Documentation for API Endpoints
148

149
150
151
Calls to GLIS API may be anonymous or use HTTP basic authentication with credentials from Easy-SMTA.

Anonymous calls are subject stricter rate limits than authenticated calls.
152

Matija Obreza's avatar
Matija Obreza committed
153
All URIs are relative to _<https://glistest.planttreaty.org>_
154

Matija Obreza's avatar
Matija Obreza committed
155
156
157
158
159
Class      | Method                                                      | HTTP request               | Description
---------- | ----------------------------------------------------------- | -------------------------- | -----------------------------------
_QueryApi_ | [**listRelationships**](docs/QueryApi.md#listRelationships) | **GET** /glisapi/v1/rels   | Get PGRFA relationships
_QueryApi_ | [**listTerms**](docs/QueryApi.md#listTerms)                 | **GET** /glisapi/v1/terms  | GLIS vocabularies
_QueryApi_ | [**search**](docs/QueryApi.md#search)                       | **GET** /glisapi/v1/pgrfas | Find passport data on PGRFA in GLIS
160

Matija Obreza's avatar
Matija Obreza committed
161
162
## Documentation for Models

163
- [Actor](docs/Actor.md)
164
165
166
167
168
169
170
171
172
173
174
175
- [ApiError](docs/ApiError.md)
- [Location](docs/Location.md)
- [Names](docs/Names.md)
- [OtherIdentifier](docs/OtherIdentifier.md)
- [PGRFA](docs/PGRFA.md)
- [RateLimitError](docs/RateLimitError.md)
- [Relationship](docs/Relationship.md)
- [Species](docs/Species.md)
- [Target](docs/Target.md)
- [Term](docs/Term.md)
- [TermValue](docs/TermValue.md)
- [UpdateInformation](docs/UpdateInformation.md)
Matija Obreza's avatar
Matija Obreza committed
176
177
178
179
180

## Recommendation

It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.

181
# Development of the library
182

183
1. Update `glis.yml` definition
184
185
186
187
188
189
2. Generate code using swagger with `mvn generate-sources`

## Testing

Unit testing is skipped by default. It can be enabled by setting `-DskipTests=false` variable and providing login credentials for the client:

Matija Obreza's avatar
Matija Obreza committed
190
```bash
191
192
GLIS_USERNAME=your_username GLIS_PASSWORD=your_password mvn test -DskipTests=false
```
193
194
195

To see debug output of API calls set envonment variable `GLIS_DEBUG=true`:

Matija Obreza's avatar
Matija Obreza committed
196
```bash
197
198
GLIS_DEBUG=true GLIS_USERNAME=your_username GLIS_PASSWORD=your_password mvn test -DskipTests=false
```
199
200
201
202
203

# Other platforms

[Swagger Codegen](http://swagger.io/swagger-codegen/) can generate client SDKs for C#, Android, C++, Haskell, Javascript, Groovy, ObjC, Perl, PHP, Python, etc.

204
Use our [glis.yml](/swagger/v1/glis.yml) to generate the API for your preferred language. If decide to make your library publicly accessible, please let us know and we'll link it here!