Skip to content

GET /serialization should support asynchronous operation for large environments #578

@DenisBiondic

Description

@DenisBiondic

# What is missing?

The GET /serialization endpoint (GenerateSerializationByIds) is defined as a synchronous request-response operation. For application/json and application/xml formats this is generally acceptable, but for application/asset-administration-shell-package+xml (AASX), serialization can be a long-running operation:

  • The server must resolve all referenced submodels and shells
  • Download all associated files (thumbnails, File submodel elements) from storage
  • Package everything into an AASX archive
  • Stream the entire result back in a single HTTP response

For environments with many shells/submodels containing many file references, this can easily exceed typical HTTP timeout thresholds and creates poor client UX (no progress feedback, no retry capability for partially completed work).

# How should it be fixed?

Consider adding an asynchronous pattern for the serialization endpoint, for example:

  1. POST /serialization that returns 202 Accepted with a Location header pointing to a status/result resource
  2. A status polling endpoint (e.g., GET /serialization-results/{requestId}) that returns 200 with the package once ready, or 202 while still processing
  3. Optionally define a progress indication in the status response

This would align with common REST async patterns (RFC 7231 §6.3.3) and give clients:

  • Timeout resilience for large packages
  • Ability to poll and show progress
  • Idempotent retry semantics

The existing synchronous GET /serialization could remain available for backward compatibility and lightweight (JSON/XML) serializations.

  • I have signed the required Developer Certificate of Origin (DCO) already.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions