ADMA API Pattern
ADMA Data Model
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.
ADMA Object 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
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:
| Description | ADMA Solution API Endpoints |
|---|---|
| Create Job | POST {ADMA-TENANT-URL}/solutions/{SOLUTION-ID}:create?api-version={ADMA-API-VERSION} |
| Fetch Status | POST {ADMA-TENANT-URL}/solutions/{SOLUTION-ID}:fetch?api-version={ADMA-API-VERSION} |
| Cancel Job | POST {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:
| Parameter | Description |
|---|---|
ADMA Tenant URL | The base URL of your ADMA service. This is unique to your tenant and ADMA instance |
Solution ID | The ADMA solution id of the AgPowered Service. Example of this is bayerAgPowered.imagery |
ADMA API Version | The 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
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:
| Description | ADMA Insight API |
|---|---|
| GET Insight | GET {ADMA-TENANT-URL}/parties/{PARTY-ID}/models/{SOLUTION-ID}/resource-types/{RESOURCE-TYPE}/resources/{RESOURCE-ID}/insights/{INSIGHT-ID}?api-version={ADMA-API-VERSION} |
| Parameter | Description |
|---|---|
ADMA Tenant URL | The base URL of your ADMA service. This is unique to your tenant and ADMA instance. |
Party ID | The ADMA Party ID that is the parent of the Resource Type/ID. |
Solution ID | The ADMA Solution ID of the AgPowered Service. Example of this is bayerAgPowered.imagery |
Resource Type | The ADMA Resource Type associated with the Resource ID. Usually Field. |
Resource ID | The ADMA Resource ID associated with the Insight that was generated. Usually Field ID. |
Insight ID | The ADMA Insight ID is the same value as the Job ID of the APS job. |
ADMA API Version | The current supported ADMA API version e.g. 2023-11-01-preview |
ADMA Insight Attachment APIs
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. File types are TIFF, TXT, JSON, etc.
The primary endpoints customers will use to interact and download Insight Attachment Objects from an APS Job are:
| Description | ADMA 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} |
| Parameter | Description |
|---|---|
ADMA Tenant URL | The base URL of your ADMA service. This is unique to your tenant and ADMA instance. |
Party ID | The ADMA Party ID that is the parent of the Resource Type/ID. |
Solution ID | The ADMA Solution ID of the AgPowered Service. Example of this is bayerAgPowered.imagery |
Resource Type | The ADMA Resource Type associated with the Resource ID. Usually Field. |
Resource ID | The ADMA Resource ID associated with the Insight that was generated. Usually Field ID. |
Insight Attachment ID | The ADMA Insight Attachment ID, this is usually retrieved from the ADMA Insight Response. |
ADMA API Version | The current supported ADMA API version e.g. 2023-11-01-preview |