Skip to content

API.md

Latest commit

 

History

History
247 lines (170 loc) · 6.36 KB

API.md

File metadata and controls

247 lines (170 loc) · 6.36 KB
Raw

DeviceLifecycle-API HTTP Contract

English | Português

Scope

DeviceLifecycle-API is a read-only HTTP extension for DeviceLifecycle. It does not query Active Directory, Microsoft Entra ID, Microsoft Intune, or Microsoft Graph directly and does not execute quarantine, restoration, or deletion actions.

DeviceLifecycle remains the authoritative producer. The API only publishes the latest CSV report and latest log generated by that service.

Current contract version: v1 (1.0.0).

Base URL

http://SERVER:8088/api/v1

The port is configurable. Plain HTTP is intended for trusted internal networks. Use an HTTPS reverse proxy whenever traffic crosses an untrusted or routed network.

Authentication

All data endpoints require:

X-API-Key: YOUR-KEY

GET /health is unauthenticated by default but can be protected with:

HealthRequiresAuthentication = $true

The key must contain at least 32 characters. The installer generates 32 random bytes represented as 64 hexadecimal characters.

The API distinguishes between:

  • 401 Unauthorized: the header was not provided;
  • 403 Forbidden: the provided key is invalid.

Common Service Metadata

JSON responses include the service identity:

{
  "service": "DeviceLifecycle-API",
  "apiVersion": "1.0.0",
  "extensionOf": "DeviceLifecycle",
  "organizationName": "orgname",
  "readOnly": true
}

Endpoints

GET /api/v1/health

Returns process availability and source-file availability.

Authentication is optional and controlled by HealthRequiresAuthentication.

Example response:

{
  "service": "DeviceLifecycle-API",
  "apiVersion": "1.0.0",
  "extensionOf": "DeviceLifecycle",
  "organizationName": "orgname",
  "readOnly": true,
  "status": "ok",
  "serverTimeUtc": "2026-07-29T16:00:00+00:00",
  "reportAvailable": true,
  "latestLogAvailable": true,
  "latestLogName": "DeviceLifecycle-20260729-021500.log"
}

status: ok indicates that the API process is operational. Validate reportAvailable and latestLogAvailable independently before assuming that source data is present.

GET /api/v1/metadata

Returns metadata for the current report and latest log without transferring file contents.

Authentication: required.

Example response:

{
  "service": "DeviceLifecycle-API",
  "apiVersion": "1.0.0",
  "extensionOf": "DeviceLifecycle",
  "organizationName": "orgname",
  "readOnly": true,
  "report": {
    "fileName": "DeviceLifecycle-Latest.csv",
    "sizeBytes": 18234,
    "lastModifiedUtc": "2026-07-29T05:15:30+00:00"
  },
  "latestLog": {
    "fileName": "DeviceLifecycle-20260729-021500.log",
    "sizeBytes": 9451,
    "lastModifiedUtc": "2026-07-29T05:15:31+00:00"
  }
}

When a source is unavailable, its corresponding property may be null.

GET /api/v1/report.csv

Returns DeviceLifecycle-Latest.csv without transformation.

Authentication: required.

Content type:

text/csv; charset=utf-8

Additional response headers:

  • Content-Disposition;
  • X-File-Name;
  • X-File-Size;
  • X-File-Last-Modified-Utc.

GET /api/v1/report

Reads the latest CSV and converts it to JSON.

Authentication: required.

Example response:

{
  "service": "DeviceLifecycle-API",
  "apiVersion": "1.0.0",
  "extensionOf": "DeviceLifecycle",
  "organizationName": "orgname",
  "readOnly": true,
  "fileName": "DeviceLifecycle-Latest.csv",
  "sizeBytes": 18234,
  "lastModifiedUtc": "2026-07-29T05:15:30+00:00",
  "recordCount": 128,
  "records": []
}

The properties inside records use the CSV headers as property names. Values remain strings to preserve the source representation.

The implementation accepts UTF-8 with or without a byte-order mark.

GET /api/v1/log?lines=500

Returns the final lines of the latest .log file as plain text.

Authentication: required.

Query parameter:

Parameter Type Default Constraint
lines integer 500 Minimum 1; maximum configured by MaxLogLines

Default MaxLogLines: 5000.

Additional response headers:

  • X-Log-File;
  • X-File-Size;
  • X-File-Last-Modified-Utc.

GET /api/v1/log/file

Returns the complete latest log as plain text.

Authentication: required.

Content type:

text/plain; charset=utf-8

Additional response headers:

  • Content-Disposition;
  • X-Log-File;
  • X-File-Size;
  • X-File-Last-Modified-Utc.

Error Responses

Errors use the FastAPI detail envelope:

{
  "detail": "Error description"
}
Status Situation
401 X-API-Key header is missing.
403 The API key is invalid.
404 The report, log directory, or latest log does not exist.
422 A parameter is invalid or the CSV cannot be parsed.
503 A stable file snapshot could not be obtained.

Unexpected application errors return 500 and are written to the rotating API log.

Common Response Headers

All responses include:

  • Cache-Control: no-store;
  • X-Content-Type-Options: nosniff;
  • X-DeviceLifecycle-API-Version: 1.0.0.

Stable File-Read Behavior

Before returning file content, the API compares file size and modification timestamp before and after the read. If the file changes while it is being read, the operation is retried. After the configured attempts are exhausted, the API returns 503 rather than exposing a potentially inconsistent snapshot.

Versioning and Compatibility

Breaking changes must use a new path prefix, such as /api/v2.

Within v1, new response properties may be added, but existing properties should not be removed or renamed. Consumers should ignore unknown properties.

Consumer Recommendations

  • Store the API key in an appropriate secret store or protected service configuration.
  • Set explicit request timeouts.
  • Check HTTP status codes before parsing the body.
  • Use /metadata when only freshness information is required.
  • Use /report.csv when the original representation must be preserved.
  • Use /report when direct JSON processing is preferred.
  • Do not assume that health.status == "ok" means the report and log are available.
  • Rotate the API key after suspected exposure and update all consumers immediately.