An API is a defined interface through which one software component accesses another component’s operations or data. In a digital twin, APIs provide structured access to internal systems and external services. A twin can request specific data when needed rather than wait for a scheduled batch or stream. Some integrations run in the other direction: webhooks notify the twin of changes, while GraphQL subscriptions and WebSockets maintain connections for updates. section 4.4.3
Choose an API style to fit the exchange:
- REST provides predictable, cacheable access to defined resources. section 4.4.3
- GraphQL lets a twin request only the attributes it needs from a richer data model. section 4.4.3
- gRPC offers type-safe, high-performance communication; WebSockets support persistent, bidirectional updates and control commands. section 4.4.3
Requesting satellite imagery
A Python request to NASA GIBS supplies a bounding box, date, image layer, dimensions, and PNG format to retrieve an image of Lake Kariba. The returned content is saved as a file. This is on-demand acquisition: the caller specifies the data it wants. section 4.4.3
Listing 4.8 Using the NASA GIBS RESTful API to retrieve an image of Lake Kariba
import requests
from datetime import datetime, timedelta
bbox = (26.5, -18.5, 29.0, -16.0) #1
yesterday = (datetime.now() - timedelta(1)).strftime('%Y-%m-%d')
params = {
'SERVICE': 'WMS',
'VERSION': '1.1.1',
'REQUEST': 'GetMap',
'LAYERS': 'VIIRS_SNPP_CorrectedReflectance_TrueColor',
'SRS': 'EPSG:4326',
'BBOX': f'{bbox[0]},{bbox[1]},{bbox[2]},{bbox[3]}',
'WIDTH': '1024',
'HEIGHT': '640',
'FORMAT': 'image/png',
'TIME': yesterday,
'TRANSPARENT': 'true'
}
response = requests.get( #2
'https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi',
params=params)
filename = f'lake_kariba_{yesterday}.png'
with open(filename, 'wb') as f:
f.write(response.content)
The listing shows the WMS request parameters, the requests.get call, and the saved response. section 4.4.3
An API is also an operational contract. Changes to schemas, rate limits, authentication, or versioning can break ingestion, so track specifications as dependencies and use versioning, tests, and monitoring to detect incompatibilities. Calls can also carry a recurring cost: an LLM API priced at $0.05 per decision costs $4.80 per day when called every 15 minutes. Model call frequency before putting an API in a frequent decision loop. section 4.4.3 section 10.3.5 section 8.5.3
Do not confuse an API used to exchange data with a digital twin model interface. A DTDL interface defines an entity’s properties, telemetry, and relationships; it describes the twin’s model rather than the request used to fetch an image. section 5.3.2 section 4.4.3
