OpenAPI Import Record Persistence

Overview

The OpenApiImportRepository is a persistence component responsible for storing and managing records of imported OpenAPI specifications. It interfaces with the s2r_openapi_import database table to provide create and read operations for these records.

The primary problem this component solves is the efficient and idempotent storage of OpenAPI specifications. It achieves this through a content-based deduplication mechanism. When an API publisher uploads a specification, a unique hash of its content is calculated. The repository uses this hash to check if an identical specification has already been imported by the same tenant, preventing redundant storage and ensuring that re-uploads of the same file do not create new records.

This repository is an internal component used by the administrative service that handles the import of API specifications. It is not directly exposed to API consumers.

How it Works

The core logic of the repository is centered on the createOrReturnExisting method, which ensures that each unique specification file is stored only once per tenant.

Idempotent Creation and Deduplication

When a request to import a new OpenAPI specification is processed, the system follows these steps:

1. A content hash (specifically, content_hash) is computed from the raw bytes of the uploaded specification file.
2. The repository first queries the s2r_openapi_import table for an existing record with a matching content_hash within the current tenant's scope.
3. If a matching record is found, the repository returns that existing record, and the process concludes. No new data is written.
4. If no matching record is found, the repository attempts to insert a new record into the database. This record includes metadata extracted from the spec (like info_title and info_version), the content hash, the raw content, and a normalized JSON representation of the spec (parsed_spec).
5. The new record is created with a unique id (UUID). Upon successful insertion, this new record is returned.
6. In the case of a concurrent import of the same file by two different processes, a race condition can occur. If the database insert fails with a DuplicateKeyException (because the other process just inserted a record with the same content_hash), the repository handles this by re-querying for the record by content_hash. It then returns the record that was just inserted by the concurrent process.

This flow is illustrated in the following diagram:

flowchart TD
    subgraph OpenAPI Import Process
        A[Start: Upload OpenAPI Spec] --> B{Calculate content_hash};
        B --> C{Query for existing record by content_hash};
        C --> D{Record found?};
        D -- Yes --> E[Return existing record];
        D -- No --> F[Attempt to INSERT new record];
        F --> G{INSERT successful?};
        G -- Yes --> H[Return new record];
        G -- No (DuplicateKeyException) --> I{Re-query for record by content_hash};
        I --> J[Return re-queried record];
    end
    J --> Z[End];
    E --> Z;
    H --> Z;

API Reference

The OpenApiImportRepository class exposes the following public methods for interacting with OpenAPI import records.

createOrReturnExisting

Creates a new import record or returns an existing one if a record with the same content_hash already exists for the tenant. This operation is idempotent.

Parameters

Returns

An OpenApiImportRecord object representing the newly created or pre-existing record.

findById

Retrieves a single OpenApiImportRecord by its unique identifier (id). The search is scoped to the current tenant.

Parameters

Returns

An Optional<OpenApiImportRecord> which contains the record if found, or is empty if no record with that ID exists for the tenant.

findByHash

Retrieves a single OpenApiImportRecord by its content_hash. The search is scoped to the current tenant.

Parameters

Returns

An Optional<OpenApiImportRecord> which contains the record if found, or is empty if no record with that hash exists for the tenant.

findParsedSpecJsonById

Fetches the normalized, parsed JSON string (parsed_spec) for a given import record ID. This provides access to the processed specification content stored in the database.

Parameters

Returns

An Optional<String> which contains the parsed JSON string if the record is found, or is empty otherwise.

Data Model

The OpenApiImportRepository persists data in the s2r_openapi_import table. The OpenApiImportRecord object returned by query methods maps to a subset of these columns.

Troubleshooting

Concurrent Uploads Resulting in DuplicateKeyException

The repository is designed to handle race conditions during concurrent uploads of identical files. If two processes attempt to create a record for the same content hash simultaneously, one will succeed, and the other will receive a DuplicateKeyException from the database.

This exception is caught and handled internally by the createOrReturnExisting method. The method will then re-fetch the record by its content_hash and return the data that the winning process successfully inserted. For the caller, this process is transparent and ensures the operation remains idempotent without returning an error.

Record Not Found

The findById, findByHash, and findParsedSpecJsonById methods return an Optional. If the returned Optional is empty, it means no record matched the specified criteria for the current tenant. This is expected behavior and not an error condition.

See Also

• WSDL Import Persistence: This component is stylistically similar to the repository that manages persistence for WSDL-based API imports.

All SOAP-to-REST docs