Welcome to the JoinData Datahub API documentation. The API documentation contains the specifications of the API's that are available in the JoinData Datahub. Also the API calls can be tested here when you have valid credentials. Feel free to play around with our API's. When you have any questions please send an e-mail to firstname.lastname@example.org.
For background information and contact details, please visit https://www.join-data.nl.
To demonstrate and test Datahub functionalities JoinData created a demo application. This application is also available to you. The URL of the application is mentioned below in the environments section. Please take note of the following remarks:
Mandates are registered in AgriTrust. To setup and maintain mandates JoinData provides an application in the integration environment and embedded AgriTrust in de website for production. The URL's are mentioned below in the environments section. Please take note of the following remarks:
The JoinData Datahub contains different services which can be used for configuration or for accessing farm data. The currently available components are:
The source register can be used for configuring the data-sources used in the Datahub. This means that is keeps an administration of the available data-sources with a configuration part. The configuration tells how to connect to the API of the data-source, how to authorize with the data-source, which type of data is available in the data-source, etc. The broker component will use the source register to find out where to route data requests.
The broker component can route data requests to third party data sources. This means when a data request is received, the Datahub determines from which data-sources the data can be retrieved and forwards the request to the API's of the appropriate data-sources. Herefore the broker handles a few important tasks:
In this section we will get you the information required to get started integrating with the JoinData Datahub.
We use the OAuth2 protocol for authentication of users and applications. Within OAuth2 we support the Authorization Code grant (https://tools.ietf.org/html/rfc6749#section-4.2). The token and authorization URL can be found by pressing the 'Authorize' button which can be found in the API specifications below.
At the moment we do not use OAuth scopes for authorization. We have integrated the AgriTrust mandate register for handling the consent of the farmer.
The JoinData Datahub provides - besides the production environment - a sandbox in which the integration can be realised and tested before going to production. Below you find the URL's for the API documentation, the demo application, the API and the authentication server.
The API documentation you are currently looking at.
The demo application as mentioned above.
The application to set up mandates as mentioned above.
The base URL of the Datahub API.
The location of the Datahub authentication service.
As our API is subject to change, we require integration parties to be flexible with their implementation. Please take care your application won't break, by keeping the following remarks in mind:
The Datahub promotes the use of ICAR-ADE standards by designing the API's based on translating the current ICAR-ADE XML/SOAP standards into the Datahub JSON/REST messages. If those standards are not available yet, new standards are developed according to the ICAR-ADE philosophy. The API design will be shared and discussed with the ICAR-ADE team on regulary basis.
For specifying data types the UN/CEFACT Common Code for Units of Measurement is used. For a full list of possible values can be found here: https://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_rev3_Annex2e.pdf.
Our API's use identification schemes for identifying resources (See each API for scheme usage). These schemes are used to indicate the type of identifier and preventing duplicate identifiers accross different countries. For now we have specified the following schemes:
nl-v1- The dutch ‘KVK’ number
nl-kvk- The dutch ‘KVK’ number
nl-v1- The dutch ’UBN’ number. See RVO for more info.
nl-ubn- The dutch ’UBN’ number. See RVO for more info.
nl-ftn- The dutch ’Milk TankId’ number
nl-kvk- The dutch ’KVK’ number
be-v1- The belgian ’FAVV’ number. See FAVV for more info.
nl-v1- The dutch 'Levensnummer' (life number) registered at RVO. See RVO for more info.
be-v1- The belgian 'Levensnummer' (life number) registered at FAVV.