GRSF API¶
- Table of contents
- GRSF API
Description¶
GRSF API (Application Programming Interface) provides a formal way of interacting directly with the GRSF Knowledge Base (KB). The GRSF API consists of a collection of various endpoints that allow searching, counting, grouping and adding new information in the GRSF KB. All the service endpoints have been implemented as REST services.
They are logically grouped in the following categories:
- insert services with the services that are implemented for adding new stock and fishery records,
- search services that allow the retrieval of one or more GRSF records or any type of information about GRSF records,
- count services that count the overall number of records with respect to several criteria,
- summary services that return the distribution of grsf records with respect to several criteria.
GRSF API Resources¶
The following table describes the existing resources that are available through GRSF API, with a brief description, the HTTP methods, and the response types.
The detailed description as well as the list of accepted parameters can be found by clicking the corresponding resources.
| Group | Resource Name | HTTP Method | Description | Response types |
|---|---|---|---|---|
| search | getstock | GET | Retrieves information about a particular stock record that exists in the GRSF KB, using its UUID. It retrieves basic stock record information and the connected time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getstocks | GET | Retrieves information about a particular stock record that exists in the GRSF KB, using several parameters. It retrieves basic stock record information and the connected time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getstockbasic | GET | Retrieves information about a particular stock record that exists in the GRSF KB, using its UUID. It retrieves only basic stock record information without time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getstocksbasic | GET | Retrieves information about a particular stock record that exists in the GRSF KB, using several parameters. It retrieves only basic stock record information without time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getfishery | GET | Retrieves information about a particular fishery record that exists in the GRSF KB, using its UUID. It retrieves basic fishery record information and the connected time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getfisheries | GET | Retrieves information about a particular fishery record that exists in the GRSF KB, using several parameters. It retrieves basic fishery record information and the connected time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getfisherybasic | GET | Retrieves information about a particular fishery record that exists in the GRSF KB, using its UUID. It retrieves only basic fishery record information without time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | getfisheriesbasic | GET | Retrieves information about a particular fishery record that exists in the GRSF KB, using several parameters. It retrieves only basic fishery record information without time-dependent data | JSON, XML, HTML, CSV, XLSX |
| search | gettraceabilityunit | GET | Retrieves information about GRSF traceability unit records that exists in the GRSF KB, using its UUID | JSON, XML |
| search | gettraceabilityunits | GET | Retrieves information about GRSF traceability unit records that exists in the GRSF KB, using several criteria | JSON, XML |
| search | fetch_uuid/stock | GET | Fetches GRSF-related information (UUID, title, semantic ID) for the stock record that has the given ID in its original data source (i.e. FIRMS, RAM, FishSource, FAO SDG 14.4.1 Questionnaire | JSON |
| search | fetch_uuid/fishery | GET | Fetches GRSF-related information (UUID, title, semantic ID) for the fishery record that has the given ID in its original data source (i.e. FIRMS, RAM, FishSource, FAO SDG 14.4.1 Questionnaire | JSON |
| search | searchspecies | GET | Searches for species using several criteria, and retrieves also the UUIDs of the related GRSF stock and fishery records | JSON, XML, CSV, HTML, XLSX |
| search | searchfishinggears | GET | Searches for fishing gears using several criteria, and retrieves also the UUIDs of the related GRSF stock and fishery records | JSON, XML, CSV, HTML, XLSX |
| search | retrieveareas | GET | Retrieves infromation about the areas (i.e. assessment areas or fishing areas) that exists in the GRSF KB. For each area, its name, code and type of code are returned, along with the corresponding record that is assigned to the area | JSON, XML |
| count | count | GET | Counts the total number of GRSF records (both stock and fishery records), that satisfy the given criteria | JSON, XML, HTML, CSV, XLSX |
| count | count/stocks | GET | Counts the total number of GRSF stock records, that satisfy the given criteria | JSON, XML, HTML, CSV, XLSX |
| count | count/fisheries | GET | Counts the total number of GRSF stock records, that satisfy the given criteria | JSON, XML, HTML, CSV, XLSX |
| summary | summary/stocks | GET | It generates a summary of GRSF stock records indicating the number of records per species, areas, types, sdg, source. | JSON, XML, HTML, CSV, XLSX |
| summary | summary/fisheries | GET | It generates a summary of GRSF fishery records indicating the number of records per species, areas, types, fishing gears, flag states, sdg, source, etc. | JSON, XML, HTML, CSV, XLSX |
| insert | addstock | POST | Adds a new stock record in the GRSF KB, and constructs the corresponding GRSF record | - |
| insert | addfishery | POST | Adds a new fishery record in the GRSF KB, and constructs the corresponding GRSF records | - |
How to use¶
GRSF API is delivered as a REST API. As such it can be used from both human (using their web browser) as well as programmatically. For humans the following access methods are recommended:
- swagger API: the front end of GRSF API is provided from swagger. This allows users access it directly from their web browser. Although it is very straightforward to use, its systematic use, especially if responses are large, is not recommended.
- postman: it is an API platform for building and using APIs, that allow testing APIs efficiently.
References¶
- GRSF API: https://isl.ics.forth.gr/grsf/grsf-api
