Skip to main content

ADMA API Pattern

ADMA Data Model

ADMA Documentation

Please review the Microsoft Azure Data Manager for Agriculture Concepts documentation for the latest content.

ADMA provides a logical data model to standardize common Agribusinesses data objects into reusable entities. The foundation of this model is the Party -> Farm -> Field heirarchy.

image

ADMA Object IDs

User Provided IDs

All ADMA Object IDs are user-provided. This includes IDs for common data objects like Fields or Parties. It also extends to APS jobs where users provide unique job IDs for job tracking.

ADMA is built on the premise that the client/user brings their own unique business entities to the platform. One of the features of this is the support of user-defined IDs for all entities. This means that the IDs that customers use today to track their objects can still be used in ADMA.

Depending on the data object, ADMA ID uniqueness constraints are scoped at different levels. For example, a field ID provided by a client must be unique within the scope of its associated Party. All Field IDs must be unique within a Party, but IDs don't have to be unique across fields in other Parties.

APS ADMA API Integration

All AgPowered Service APIs are accessed using the ADMA Solutions API, which is a generic ADMA API interface to submit ASYNC API requests to an AgPowered Service (APS). The outputs of an APS job are written to the client ADMA tenant.

If a client is interested in downloading the outputs of an APS job to a different location, the outputs of an APS Job can be retrieved using either the ADMA Insights API or the ADMA Insight Attachement API. (See the ADMA Insights and Insight Attachment APIs section for more details )

The call flow for a client interacting with ADMA and AgPowered Services can be visualized as follows:

ADMA APS Asynchronous Client API Call Flow

image

ADMA Solutions API

An AgPowered Service is referenced in the ADMA Solutions API using the Solution ID of the service. The ADMA Solutions API exposes 3 endpoints that are used to proxy requests to Bayer AgPowered Services. These are:

DescriptionADMA Solution API Endpoints
Create JobPOST {ADMA-TENANT-URL}/solutions/{SOLUTION-ID}:create?api-version={ADMA-API-VERSION}
Fetch StatusPOST {ADMA-TENANT-URL}/solutions/{SOLUTION-ID}:fetch?api-version={ADMA-API-VERSION}
Cancel JobPOST {ADMA-TENANT-URL}/solutions/{SOLUTION-ID}:cancel?api-version={ADMA-API-VERSION}

Key parameters required for using the ADMA Solutions API to interact with AgPowered Services are:

ParameterDescription
ADMA Tenant URLThe base URL of your ADMA service. This is unique to your tenant and ADMA instance
Solution IDThe ADMA solution id of the AgPowered Service. Example of this is bayerAgPowered.imagery
ADMA API VersionThe current supported ADMA API version e.g. 2023-11-01-preview

ADMA Insights and Insight Attachment APIs

All AgPowered Services write the results of a job back to a customer's ADMA Tenant as ADMA Insights and Insight Attachments. ADMA Insights and Insight Attachments are related concepts, the basic definition of each:

ADMA Insight: JSON objects associated with a given APS job run to record Attribute results and diagnostics about the job. Insight ID is the same as the APS Job ID.

ADMA Insight Attachments: Child objects of an Insight Object that are Files generated by an APS job that can be downloaded or managed via the Insight Attachments API. List of Insight Attachments can be retrieved from the Insight Object JSON.

ADMA Insights API

ADMA Insights API

The ADMA Insights API exposes a suite of endpoints that can be used to manage, discover, and retrieve Insights on ADMA. Please review the ADMA Insights API Documentation for a complete overview.

The primary endpoint customers will use to interact with Insight Objects from an APS Job is:

DescriptionADMA Insight API
GET InsightGET {ADMA-TENANT-URL}/parties/{PARTY-ID}/models/{SOLUTION-ID}/resource-types/{RESOURCE-TYPE}/resources/{RESOURCE-ID}/insights/{INSIGHT-ID}?api-version={ADMA-API-VERSION}
ParameterDescription
ADMA Tenant URLThe base URL of your ADMA service. This is unique to your tenant and ADMA instance
Party IDThe ADMA Party id that is the parent of the resources type/id.
Solution IDThe ADMA solution id of the AgPowered Service. Example of this is bayerAgPowered.imagery
Resource TypeThe ADMA Resource Type associated with the Resource ID. Usually Field.
Resource IDThe ADMA Resource ID associated with the Insight that was generated. Usually Field ID.
Insight IDThe ADMA Insight ID, this is the same value as the Job ID of the APS job.
ADMA API VersionThe current supported ADMA API version e.g. 2023-11-01-preview

ADMA Insight Attachment APIs

ADMA Insight Attachments API

The ADMA Insight Attachments API exposes a suite of endpoints that can be used to manage, discover, and retrieve Insights Attachments (files) on ADMA. Please review the ADMA Insight Attachments API Documentation for a complete overview.

ADMA Insight Attachments are the file outputs generated by an APS job, these can be file types such as TIFF, TXT, JSON, etc.

The primary endpoints customers will use to interact and download Insight Attachment Objects from an APS Job are:

DescriptionADMA Insight Attachment API
GET Insight Attachment (metadata about file)GET {ADMA-TENANT-URL}/parties/{PARTY-ID}/models/{SOLUTION-ID}/resource-types/{RESOURCE-TYPE}/resources/{RESOURCE-ID}/insight-attachments/{INSIGHT-ATTACHMENT-ID}?api-version={ADMA-API-VERSION}
DOWNLOAD Insight Attachment (Byte Stream)Download {ADMA-TENANT-URL}/parties/{PARTY-ID}/models/{SOLUTION-ID}/resource-types/{RESOURCE-TYPE}/resources/{RESOURCE-ID}/insight-attachments/{INSIGHT-ATTACHMENT-ID}/file?api-version={ADMA-API-VERSION}
ParameterDescription
ADMA Tenant URLThe base URL of your ADMA service. This is unique to your tenant and ADMA instance
Party IDThe ADMA Party id that is the parent of the resources type/id.
Solution IDThe ADMA solution id of the AgPowered Service. Example of this is bayerAgPowered.imagery
Resource TypeThe ADMA Resource Type associated with the Resource ID. Usually Field.
Resource IDThe ADMA Resource ID associated with the Insight that was generated. Usually Field ID.
Insight Attachment IDThe ADMA Insight Attachment ID, this is usually retrieved from the ADMA Insight Response.
ADMA API VersionThe current supported ADMA API version e.g. 2023-11-01-preview