eNVD API for developers
- Peter Quigley (Unlicensed)
- Emily Duncanson (Unlicensed)
- 1 About
- 1.1 eNVD
- 2 About GraphQL
- 3 Authentication
- 3.1 Request headers
- 3.1.1 Request body
- 3.1.2 Example header
- 3.1.3 Example body
- 3.1.4 Response body
- 3.1.5 Example body
- 3.2 Response codes
- 3.1 Request headers
- 4 Program accreditation
- 5 Using the GraphQL API
- 5.1 Examples
- 5.1.1 Retrieving a consignment
- 5.1.2 Create a consignment
- 5.1.3 Benefits
- 5.1.4 Update a consignment
- 5.1.5 Printing a consignment
- 5.2 Mapping from Forms to Questions
- 5.1 Examples
- 6 FAQ
- 7 Appendix
About
eNVD
eNVD stands for electronic National Vendor Declaration. The Livestock Production Assurance NVD communicates the food safety and treatment status of every animal every time it moves – between properties, to saleyards, or to processors. The NVD also acts as movement documentation throughout the value chain.
NVDs are a legal document that are key to Australian red meat’s traceability and market access. It is crucial that the NVD is filled out accurately, when users tick a box or answer a question on the LPA NVD, they are declaring their on-farm practices meet LPA requirements, and ultimately customer expectations.
Their tick must be backed up by accurate farm records. This is a pledge that the meat from their farm has been produced safely, ethically and meets biosecurity requirements– it means they stand by what you sell.
eNVD is the digital process for assuring and moving livestock. It is a fast and easy way for users to complete livestock consignments and maintain LPA records. The system will be continuously improved to create better experiences for users and add value to our industry’s integrity. For more information, visit the ISC website here.
The eNVD API is available to integrators that deliver livestock assurance and movement related solutions to the Australian red meat industry. Licensed integrators are transitioning from REST to GraphQL with further details below.
About GraphQL
GraphQL is a syntax that describes how to ask for or manipulate data, and is generally used to load data from a server (eNVD) to a client (you), or for you to create or request changes to data.
GraphQL has three main characteristics:
It lets the client specify exactly what data it needs.
It makes it easier to aggregate data from multiple sources.
It uses a type system to describe data.
With GraphQL, the client is able to make a single call to fetch the required information rather than to construct several REST requests to fetch the same. The client is also able to easily understand what is available in the API and how to request it as the endpoint itself provides such documentation via an introspection query.
eNVD uses GraphQL as it offers more flexibility for developers. The option to precisely create or retrieve a consignment (or multiple consignments) including the information that a user wants is a great advantage over sending multiple REST calls to achieve the same.
Visit the GraphQL website to learn more about how GraphQL works.
Authentication
eNVD requires clients to use an API key which will allow application users to login.
You can then login users from 2 different systems.
LPA users - Full read/write access
NLIS users - Read access, read/write access for transporters
You can apply for a API key by emailing technicalsupport@IntegritySystems.com.au.
The eNVD API uses JSON web tokens. When an HTTP POST request is sent to the Auth Server, a valid token is returned or an invalid request. The returned token must then be passed in as a request header with all future requests.
To request a token in production, call the following URI : auth.integritysystems.com.au/connect/token
To request a token in UAT, call the following URI : auth-uat.integritysystems.com.au/connect/token
Request headers
HTTP Header | Description | Example |
|---|---|---|
Content-type | The MIME type of the body of the request | Content-Type: application/x-www-form-urlencoded |
Request body
HTTP Body | Description | Example |
|---|---|---|
Client ID | Client identifier of your application | client_id=mySuperApp |
Client Secret | Your assigned client secret | client_secret=mysecret |
Grant Type | We use Password Grant Type | grant_type=password |
Scope | Available values include lpa_scope or nlis_scope, dependent on your user | scope=lpa_scope |
UserName | When the scope is for LPA users, the username is the PIC-userid (note the - between PIC and userid) | username=Q1KK0786-1005672 |
Password | The account holder's relevant password | password=userpassword |
Example header
Content-Type: application/x-www-form-urlencodedExample body
client_id=mySuperApp&client_secret=mysecret&grant_type=password&scope=lpa_scope&username=Q1KK0786-1005672&password=userpasswordResponse body
HTTP Body | Description | Example |
|---|---|---|
access_token | The access token returned | "access_token" : "eyJ0eXAiOiJKV1Q..." |
expires_in | Number of minutes the token will be valid for | "expires_in" : "3600" |
token_type | The type of token generated by the API | "Bearer" |
Example body
{
"access_token" : "eyJ0eXAiOiJKV1Q...",
"expires_in" : "3600",
"token_type" : "Bearer"
}Response codes
If a response code of 200 is returned, it means you have successfully authenticated and can access your token.
If a response code of 400 is returned, it could mean that your api key is invalid by indicating you are an invalid client or your username or password is invalid.
For other response codes, check the message included in the body of the response object.
Program accreditation
To be able to create an NVD via the eNVD system, a user must be LPA accredited. The table below outlines the program accreditation required for each type of form supported by eNVD.
Forms |
| Program Accreditation | |||
|---|---|---|---|---|---|
| LPA | EU | MSA | NFAS | |
NVD | ✓ |
|
|
| |
NVD EU | ✓ | ✓ |
|
| |
MSA | ✓ |
| ✓ |
| |
NFAS | ✓ |
|
| ✓ | |
NFAS EU | ✓ | ✓ |
| ✓ | |
Health Dec |
|
|
|
| |
Using the GraphQL API
Must like a REST API, interacting with a GraphQL API involving making calls to the endpoint in way that follows GraphQL rules and the types of the API. For initial learning and experimentation we recommend two use either:
Playground, a web based interface which is available by navigating in your browser to one of our GraphQL API endpoints
Please review the documentation for each tool to learn how to use it to interact with a GraphQL API.
Examples
The following examples provide some eNVD specific context to how interactions with the GraphQL API work. Please bare in mind that these are examples only and queries should be modified to suit your needs, such as reducing the fields in the requests to only ask for the data you need.
Retrieving a consignment
In the existing REST API, retrieving a consignment and its forms and subforms would require multiple requests. Using GraphQL this process can be simplified to look more like the below, asking for all information in a single call. Note that there are inline comments to help explain what each field is:
A single consignment request is similar, and you would list fields the same as those in the items field above.
Notice now that there is only one (1) endpoint at /graphql which you can query for data from within Forms, Subforms and the URL for the printed Consignment.
Create a consignment
Previously, in the V3 API, there were multiple REST calls required in order to create a consignment and attach forms and subforms to it. Each of them had to be done individually in a sequence such as:
With the GraphQL API you now only need to make one call (called a mutation) as shown below. Note that questions and answers are now centralised, with the answers automatically mapped out to all relevant forms. You also have the opportunity to define the information that you want to receive in return for the successful call, which helps enable verifying changes are as expected and keeping in sync.
Benefits
As can be seen in the above example, you won’t need to:
Create each form individually
Create each subform individually
Duplicate answers across forms and subforms
Use multiple endpoints to achieve this, only 1 call is required!
This helps reduce the number of calls which reduces network traffic and the time to process a query or change. Importantly, it also ensures alignment in the data across all forms.
Update a consignment
An update looks very similar to a create, where you provide what is essentially a patch of the information you wish to change again using a mutation. With partial updates you just provide the information you want to change, not a complete picture of how the data must be after the change.
Printing a consignment
In a consignment query or mutation there is a field pdfUrl which, if requested, contains a URL which can be used to print the consignment.
Mapping from Forms to Questions
As seen in the above examples, part of the move from the REST API to the GraphQL API is understanding how the new format of questions and answers maps back to forms and subforms. To help navigate this mapping, the attached json file contains mappings between the two.
It contains an array of entries such as:
In this entry there are 3 pieces of information to help you find the form and subform based piece of information, such as how it would referred to using the REST API:
“Text” - The question text that is presented to the user. This helps to double check that the question is the right one, and provides text they can choose to use in their system.
“Form”- The form that the question links to. There are separate entries in the JSON for each form, so if a question is used for multiple forms (which is often the case) then it will appear multiple times, once for each form. Note that form names have had their periods removed, so LPA.C.1 will be LPAC1 in the JSON.
“Field” - This points to the JSON schema field in the form model, and is the way that integrators can map between the old model using this field and ‘Form’, and the new model which uses ‘ID’
As a further example / explanation of the “Field”, given the following excerpt from the MSA form model:
the MSA Registration no. of owner would be identified as:
The final piece of information is to help you map this to the new question and answer format used in the GraphQL API:
“ID” - This is the ID of the question in its new structure, and will become the new way that integrators refer to a question instead of their json path
FAQ
Are there limits as to how much I can request in one call?
We trust that consumers will operate a fair use manner, only requesting the data they require at the rate which they require it. An example of this would be a query for the 20 most recently modified consignments for a list. For such a scenario it is generally reasonable to request just the high level information for each consignment, leaving the detail for future calls.
How are errors handled?
A successful request returns a status of 200, however unlike a REST API call, that does not mean your query or mutation was successful. Instead you need to look in the body of the response and check if any errors were returned.
See https://graphql.org/learn/serving-over-http/#response for more detail.
How is the performance compared to the REST API?
The performance is excellent, however it does depend on what is requested in some ways that can be appreciated. If you are requesting a large amount of data and the resolution takes a while then that single GraphQL query may take some time to return. Given however that this is achievable in a single call with generally no further calls required, the result is greatly improved overall performance.
How can I request form data if we’re no longer submitting the data as forms?
The change to store and manage a consignment a set of questions and answers abstracted away from forms generally removes the need for querying the data in the structure of a particular form. Having said that, you can, if you wish, query for the data for a specific form and the API will provide that to you, mapping from the consignment and its questions and answers format to the form in question. From a consumer’s perspective this means that your queries and mutations in general are vastly simplified, and for the rare case when the data is required in a specific form’s shape, it is possible.
Do we need to use the questions, help, hint and other text you provide within our systems?
It is advised to use this information to provide users with a unified experience and to ensure that the wording surrounding a question stays aligned with how the question is used and what it means. Moving away from the usage of these fields puts the onus on API consumers to monitor them for updates and keep the wording in their implementation aligned.
When I’m making calls in Playground it is saying that I am not authenticated, how can I fix this?
Playground provides an interface to make queries to the GraphQL API, much like tools such as Insomnia and Postman. To make calls to an authenticated endpoint you must provide authentication headers much as you would for a call using any other tool. Within Playground there is a section where you can enter headers in JSON format, located in the version at the time of writing at the bottom of the screen. It is here that you need to correctly construct the Authorization header that is required along with a valid token, and Playground will pass this along with your calls which will then succeed.