JoinData Datahub API documentation

Introduction

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 tech@join-data.nl.

For background information and contact details, please visit https://www.join-data.nl.

Demo application

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:

  • The demo application requires EHerkenning for authentication.
  • Data can be retrieved for locations (for scheme nl-v1: ubn's) belonging to the company of the EHerkenning agent (for scheme nl-v1: KvK-numbers).
  • A mandate must be present for the data groups you wish to obtain. The company belonging to the EHerkenning agent should mandate the developer of the demo app: Rovecom OpMaat B.V.

Mandate application

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 mandate application requires EHerkenning for authentication.

Services

The JoinData Datahub contains different services which can be used for configuration or for accessing farm data. The currently available components are:

Source register

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.

Broker

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:

  • Checking if the owner of the data (farmer) has authorized the requesting party (application) to access this data
  • Keep an administration of which data-sources has which information for each farm
  • Standarizing the format of data

Getting started

In this section we will get you the information required to get started integrating with the JoinData Datahub.

Security

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.

Environments

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.

API documentation service

The API documentation you are currently looking at.

Demo application

The demo application as mentioned above.

Mandate application

The application to set up mandates as mentioned above.

API

The base URL of the Datahub API.

Authentication server

The location of the Datahub authentication service.

Notes for integration parties

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:

  • New endpoints can be added to the API.
  • New fields can be added to messages (request and response).
  • This documentation will be updated and is maintained by JoinData.
  • At a later stage in time we probably will create some sort of developer portal.
  • Our API uses versioning. Version number changes will only be introduced if there are incompatible structural changes. Previous versions will be deprecated and will have a limited lifetime.

Additional information

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.