API docs by Redocly

Datamesh OData Service Root (Entity Set Discovery) (2.0.0)

Download OpenAPI specification:

This document describes the OData service root endpoints for both v1 and v2 versions of the OData service.

The service root is typically the entry point you call to discover what entity sets are available in the service. The response contains an array of objects, each representing an entity set:

  • name: The entity set name as exposed by the OData service (collection endpoint).
  • url: The relative path you use to query that entity set (for example: /fleet, /mcc, /asset).

In other words, this endpoint helps clients dynamically discover the navigation surface of the API without hardcoding entity set names.

Version Differences:

  • v1: Exposes entity sets from classic DRM: fleet, clients, mcc, asset, documents
  • v2: Exposes entity sets from DRM NG: fleet, mcc

Introduction

Welcome to the Datamesh OData API

API Architecture

Aircraft maintenance, lease management, and operational data are generated across multiple enterprise systems such as AMOS, AVIATAR MRO Management, mobile applications, and desktop applications. These systems are optimized for operational workflows but do not provide a unified, standardized view of data for downstream consumers.

DataMesh acts as a centralized integration and data access layer that bridges the gap between operational systems and business consumers. It enables consistent data synchronization, transformation, storage, and exposure through standardized APIs, reducing the complexity of direct system-to-system integrations.

How DataMesh Works

API Architecture

  1. Maintenance and asset-related events are generated within AMOS and AVIATAR applications.
  2. These events are routed through the AMOS Central Cloud Environment using a message-based communication model.
  3. The AMOS Central Queue Listener consumes incoming messages from the cloud platform.
  4. DataMesh processes, validates, enriches, and transforms the incoming data into a standardized data model.
  5. Processed information is stored in dedicated databases:
  • Lease Asset Management Database
  • Data Record Management Database
  1. DataMesh exposes the consolidated data through OData APIs, allowing internal and external consumers to access information consistently and efficiently.

Key Benefits of DataMesh

  • Single Source of Truth for lease asset and maintenance-related data
  • Decouples Source Systems from downstream consumers
  • Event-Driven Architecture for near real-time data synchronization
  • Standardized OData APIs for easy data access and integration
  • Scalable Integration Platform that can onboard additional systems with minimal impact
  • Improved Data Governance through centralized processing and storage

Architecture Overview

Why and How DataMesh Enables Seamless Data Integration Across the Aviation Ecosystem

DataMesh serves as the central integration and data distribution platform, consuming operational data from AMOS and AVIATAR, transforming it into a standardized model, persisting it in domain-specific repositories, and exposing it through OData APIs for downstream consumers.

API Architecture

Getting Started

  1. Authenticate: Obtain an access token using the OAuth 2.0 refresh token flow

Download the Postman collection and watch the setup guide video

  1. Discover Available Services: Start by calling the service root endpoint (/v1 or /v2) to discover available entity sets

  2. Explore Metadata: Use the $metadata endpoint to understand entity structures and properties

  3. Query Data: Use OData query options such as $filter, $select, $expand, $orderby, $top, and $skip to retrieve data

API Versions

  • v1: Legacy version with broader entity set coverage (fleet, clients, mcc, asset, documents)
  • v2: Modern version focused on core operations (fleet, mcc)

Common Use Cases

  • Query aircraft tail information
  • Retrieve work packages and work orders
  • Filter and expand related entities
  • Access maintenance documentation

Authentication

OAuth 2.0 token endpoints for authentication

Postman Variables

The following environment variables can be used to configure API requests:

  • {{CLIENT_ID}}: OAuth 2.0 client identifier (e.g., flydocs)
  • {{CLIENT_SECRET}}: OAuth 2.0 client secret (e.g., MMD6QhiYKsZO5gBJmghsGK8RwKcqHLjC)
  • {{REFRESH_TOKEN}}: Valid refresh token to obtain access tokens

API Architecture

Postman Pre-request Script

/**
* Common token bootstrap for all requests in this folder.
* - Reuses token if present
* - Fetches token if missing
* Optionally extend to refresh based on expires_in.
  */
  pm.sendRequest({
url: "https://sso-dev.apps.aviatar.io/auth/realms/ecosystem/protocol/openid-connect/token",
method: "POST",
header: { "Content-Type": "application/x-www-form-urlencoded" },
body: {
  mode: "urlencoded",
  urlencoded: [
    { key: "client_id", value: pm.variables.get("CLIENT_ID") },
    { key: "client_secret", value: pm.variables.get("CLIENT_SECRET") },
    { key: "refresh_token", value: pm.variables.get("REFRESH_TOKEN") },
    { key: "grant_type", value: "refresh_token" }
  ]
}
}, (err, res) => {

if (err) throw new Error("Token call failed: " + err);

    const json = res.json();
    if (!json.access_token) {
      throw new Error("No access_token in response: " + res.text());
    }

    pm.environment.set("bearerToken", json.access_token);

// Optional: store expiry timestamp (seconds -> ms)
  if (json.expires_in) {
  pm.environment.set("datamesh_access_token_expires_at", String(Date.now() + (json.expires_in * 1000)));
}
});

API Architecture

Get Access Token

Obtain an access token using the OAuth 2.0 refresh token flow.

This endpoint is used to authenticate and retrieve a bearer token required for accessing all API endpoints.

Authentication Flow:

  1. Send a POST request to the token endpoint with your credentials
  2. Receive an access token and refresh token in the response
  3. Include the access token in the Authorization header for subsequent API requests
  4. Refresh the token before it expires using the refresh token

Example Usage:

curl -X POST {{SSO_URL}}/auth/realms/ecosystem/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={{CLIENT_ID}}" \
  -d "client_secret={{CLIENT_SECRET}}" \
  -d "refresh_token={{REFRESH_TOKEN}}" \
  -d "grant_type=refresh_token"
Authorizations:
bearerAuth
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

OAuth 2.0 client identifier

client_secret
required
string

OAuth 2.0 client secret

refresh_token
required
string

Valid refresh token to obtain a new access token

grant_type
required
string
Value: "refresh_token"

OAuth 2.0 grant type

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expires_in": 3600,
  • "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "token_type": "Bearer",
  • "refresh_expires_in": 1800,
  • "scope": "openid profile email"
}

Service Discovery (v1)

Version 1 endpoints - Legacy version with broader entity set coverage

Discover available OData entity sets (v1)

Returns the OData service root document for version 1. Use this endpoint as the first step in client workflows to enumerate the entity sets exposed by the service.

Available entity sets in v1:

  • fleet: Fleet management data (Aircraft, Engine, APU, Gears etc)
  • clients: Client information
  • mcc: Maintenance Control Center data (WorkPackages, Workorders)
  • asset: Asset management data
  • documents: Document management data

Typical usage:

  1. Call the service root (/v1) to retrieve entity set names and relative URLs.
  2. Select an entity set you want to work with (for example: asset).
  3. Follow the discovered url to issue OData queries (commonly including $metadata, $select, $filter, $orderby, and paging options).

The response format follows OData conventions. The value array lists entity sets, while @odata.context provides context information for OData responses.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "/",
  • "value": [
    ]
}

Get metadata for the Asset service area

Retrieves the $metadata document for the asset portion of the OData service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "$Version": "4.01",
  • "assetManagement": {
    }
}

Lease Asset Management

Endpoints for managing lease asset return conditions, major assemblies, and related asset data

Query Major Assembly Return Conditions

Retrieves a collection of MajorAssemblyReturnConditions entities from the asset entity set in v1. This endpoint allows filtering by MSN (Manufacturer Serial Number) and expanding related ReturnConditions.

Example Usage:

/v1/asset/MajorAssemblyReturnConditions?$filter=Msn eq 'TBA001'&$expand=ReturnConditions

Response Structure Explanation:

The response contains major assembly return condition records with the following key fields:

  • LeaseReturnDate: The expected date for lease return of the aircraft (ISO 8601 format: "YYYY-MM-DD")
  • Msn: Manufacturer Serial Number - unique identifier for the aircraft
  • Id: Unique identifier for the major assembly return condition record
  • AircraftRegistration: The aircraft registration code/tail number
  • ReturnConditions: Array of nested return condition details for various assemblies

Each item in the ReturnConditions array contains:

  • SerialNumber: Serial number of the specific assembly/component (null if not applicable)
  • AssemblyName: Name/identifier of the assembly (e.g., "Engine", "Landing Gear", "Airframe", "APU")
  • ReturnConditionStatus: Status code indicating the return condition state
    • "0": >50%
    • "1": <50%
    • "2": No Issues
    • Additional status codes may represent Completed, Failed, etc.
  • Id: Unique identifier for the return condition record

How to use the endpoint:

  1. Call the service root (/v1) to discover available entity sets
  2. Call /v1/asset/$metadata to discover entity structures and properties
  3. Query the entity set with $filter to filter by specific MSN
  4. Use $expand=ReturnConditions to include nested return condition details
  5. Optionally use $select to limit returned fields
Authorizations:
bearerAuth
query Parameters
$top
integer >= 1

Limit the number of results returned

$skip
integer >= 0

Skip a specified number of results (for pagination)

$select
string

Select specific properties to return, e.g., Msn,AircraftRegistration,LeaseReturnDate

$filter
string

Filter criteria, e.g., Msn eq 'TBA001'

$expand
string

Expand related entities, e.g., ReturnConditions

$orderby
string

Sort results by specified properties

header Parameters
Amos-Central-Address
required
string
Example: com.flydocs.flybrary.test

Customer-specific Amos Central sender address used to identify the requesting client and apply data access filtering.

Example: com.flydocs.flybrary.test

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "$metadata#MajorAssemblyReturnConditions(ReturnConditions())",
  • "value": [
    ]
}

Service Discovery (v2)

Version 2 endpoints - Legacy version with broader entity set coverage

Discover available OData entity sets (v2)

Returns the OData service root document for version 2. Use this endpoint as the first step in client workflows to enumerate the entity sets exposed by the service.

Available entity sets in v2:

  • fleet: Fleet management data
  • mcc: Maintenance Control Center data

Note: v2 provides a streamlined set of entity sets compared to v1, focusing on core fleet and maintenance operations.

Typical usage:

  1. Call the service root (/v2) to retrieve entity set names and relative URLs.
  2. Select an entity set you want to work with (for example: fleet).
  3. Follow the discovered url to issue OData queries (commonly including $metadata, $select, $filter, $orderby, and paging options).

The response format follows OData conventions. The value array lists entity sets, while @odata.context provides context information for OData responses.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "/",
  • "value": [
    ]
}

Get metadata for the Fleet service area

Retrieves the $metadata document for the fleet portion of the OData service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "$Version": "4.01",
  • "fleet": {
    }
}

Get metadata for the MCC service area

Retrieves the $metadata document for the mcc portion of the OData service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "$Version": "4.01",
  • "com.flydocs.datamesh.model_v2.mcc": {
    }
}

Data Record Management

Endpoints for managing maintenance control center data including work packages, work orders, and related documentation

Query Fleet AircraftTails entities

Retrieves a collection of AircraftTails entities from the fleet entity set.

Example Usage:

/v2/fleet/AircraftTails?$top=3

How to use "any entity" (OData flow):

  1. Call the service root (/) to discover available areas (e.g., fleet).
  2. Call /<area>/$metadata (e.g., /fleet/$metadata) to discover entity set names and properties.
  3. Query an entity set by calling /<area>/<EntitySetName> (e.g., /fleet/AircraftTails).
Authorizations:
bearerAuth
query Parameters
$top
integer >= 1
$skip
integer >= 0
$select
string
$filter
string
$orderby
string

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "$metadata#AircraftTails",
  • "value": [
    ]
}

Query MCC WorkPackages by Tail ID

Retrieves a collection of WorkPackages entities from the MCC entity set for a specific tailId. The tailId filter is required.

Example Usage:

/v2/mcc/workpackages?$filter=tailId eq '9fad7ed8-61e3-4056-b013-acea43934a28'&$top=1&$skip=2

How to use the endpoint:

  1. Call the service root (/) to discover available areas (e.g., mcc).
  2. Call /<area>/$metadata (e.g., /mcc/$metadata) to discover entity set names and properties.
  3. Query an entity set by calling /<area>/<EntitySetName> (e.g., /mcc/workpackages) with the $filter parameter to apply a specific tailId.
Authorizations:
bearerAuth
query Parameters
$top
integer >= 1
$skip
integer >= 0
$select
string
$filter
required
string
$orderby
string

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "$metadata#workpackages",
  • "value": [
    ]
}

Query MCC WorkPackages with multiple filters and expand Workorders

Retrieves a collection of WorkPackages entities from the MCC entity set in v2 with support for filtering by tailId and clientId, and expanding related Workorders with selective properties.

Example Usage:

/v2/mcc/workpackages?$filter=tailId eq '9fad7ed8-61e3-4056-b013-acea43934a28'&$expand=Workorders($select=id,orderNo,type,workStatus,tagNames)

How to use the endpoint:

  1. Call the service root (/v2) to discover available areas (e.g., mcc).
  2. Call /v2/<area>/$metadata to discover entity set names and properties.
  3. Query the entity set with $filter to apply specific criteria (e.g., tailId and clientId).
  4. Use $expand to include related entities (e.g., Workorders) with optional $select to limit properties.
Authorizations:
bearerAuth
query Parameters
$top
integer >= 1
$skip
integer >= 0
$select
string
$filter
string

Filter criteria, e.g., tailId eq '9fad7ed8-61e3-4056-b013-acea43934a28'

$expand
string

Expand related entities, e.g., Workorders($select=id,orderNo,type,workStatus)

$orderby
string

Responses

Response samples

Content type
application/json
{
  • "@odata.context": "$metadata#workpackages",
  • "value": [
    ]
}