Using the Data Hub
This page is part of the Developer Documentation and zooms in on how you can use the DataHub service of JoinData. The DataHub is the part of JoinData where you can consume data. Application providers can send a request for data to this API via a REST call. The broker checks whether a mandate is present and retrieves the requested data from available source(s).
Introduction
To be able to consume data via JoinData, you will need an account (more specifically, an OAuth2 client) and consent from the farmer (a mandate).
The account you will get during the onboarding process. There are two environments you can use: the integration environment for testing your integration and a production environment. They require separate accounts. For more information, see Developer Documentation: Identification and Authentication.
The consent from the farmer to be able to use his or her data can be retrieved in multiple ways. Typically this is done via the onboarding procedure as described in Developer Documentation: Using the Purpose Registry.
Some of the static data flows are not (yet) exposed via the DataHub, these are accessible via the EDI-Circle API.
Data format
The DataHub delivers data in standardised formats.
Currently, most messages are defined in ICAR ADE standards. 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. Other standards may be added when applicable.
Querying
The DataHub API’s look roughly as follows: /{standard}/{object}/{message}.
Errors
As is custom with REST API’s, the HTTP status code tells you if the call is successful or not, and if not, who needs to take action. To summarize:
- If you receive a status code in the 200 range, your request was successful and in the body you can find the requested message.
- If the status code is in the 500 range, something went wrong on our side. Please contact support@join-data.nl
- If the status code is in the 400 range, something went wrong on your side.
In the 400 range, you will always get a (list of) error messages in the body of the response. Each error message consists of a title, description, and an id.
The title gives you a short summary of what the problem is. The description is meant for developers to indicate in more detail what went wrong and how to fix it. The id is meant for automation; you can take automated actions based on this specific error if you want to.
Some of the common errors are these:
{"errors": [{ "id": "auth_failed", "title": "Authentication failed", "description": "Authentication failed. Invalid or expired token." } ] }
In this case, you have queried some end-point with an invalid token. The token you have retrieved is invalid or expired. Use your refresh token to get a new one.
{"errors": [{ "description": "The requested location does not exist. Please check your request path and make sure it is valid.", "title": "Location not found", "id": "location_not_found" } ] }
In this case, you have queried a message for a farm that does not exist, at least not in our administration. Check if you have the correct scheme, identifier or if the farmer is onboarded with JoinData.
{"errors": [{ "description": "There was no mandate found for the request. Please make sure there is a mandate provided to your company and for the requested location and data type in the mandate register. This mandate needs to be provided by the farmer who owns the requested location.", "title": "Mandate not found", "id": "mandate_not_found" } ] }
In this case you have queried for data that you do not (yet) have a mandate for. Check Developer Documentation: Using the Purpose Registry on how to get consent from the farmer.
{"errors": [ { "description": "The requested location scheme is invalid. Please check your request path and make sure it is valid.", "title": "Location scheme is invalid", "id": “location_invalid_scheme” } ] }
In this case, you have queried some end-point with a location scheme that we do not recognise. Most objects are identified by using a scheme and identifier. Check what the scheme is that you are using and if it is supported by JoinData for that message.
Postman
To communicate with our API’s Postman can be used. On the API-docs page a Postman-collection with all relevant API-calls can be found. Postman can be downloaded here.
To make a successful call please follow the next steps:
1. Retrieve acces token using the credentials you have received from JoinData
2. Select the end-point you wish to retrieve, for instance herd-list.
3. Go to the params and set the correct parameters. For Dutch farms the location-scheme is nl-v1, the location-id is the UBN. Start- and end-date-time parameters are set following the ISO-8601 standard, in the folowing format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss] (e.g. 2018-01-24T23:45:00).
4. Click send and wait for JoinData to retrieve the requested information at the availables sources.
5. When you get an error message, please resolve the mentioned error (e.g. retrieve new access token of set required mandate). If you can not resolve the error, please contact tech@join-data.nl.