Operations and processes

PdfAPI performs 13 distinct operations behind its 13 endpoints: document conversion, merging, page extraction, tracking-record persistence and polling, tracked-document download, and six stateless PDF inspection/validation checks. This page is the operation catalog and hub; each operation's step-by-step logic lives in its own page under operations/.

Operation catalog

ID	Operation	Entry endpoint	Trigger	Owning component	Rules
OP-CONVERT-REQUEST	Convert (request-shaped)	POST v1/convert	Client submits a ConvertRequest body	ConvertController.Convert(ConvertRequest)	BR-PDFAPI-003, BR-PDFAPI-008, BR-PDFAPI-009, BR-PDFAPI-010, BR-PDFAPI-016, BR-PDFAPI-017, BR-PDFAPI-019, BR-PDFAPI-020
OP-CONVERT-FILE	Convert (file-shaped)	POST v1/convert/{fileExtension}	Client submits raw bytes plus a route-supplied extension	ConvertController.Convert(byte[] file, string fileExtension, PdfFormat format)	Same rule set as OP-CONVERT-REQUEST
OP-EXTRACT-PAGES	Extract pages	POST v1/extract	Client submits an ExtractPagesRequest	ExtractController.Extract(ExtractPagesRequest)	BR-PDFAPI-004, BR-PDFAPI-005, BR-PDFAPI-010, BR-PDFAPI-016, BR-PDFAPI-017, BR-PDFAPI-018
OP-MERGE-DOCUMENTS	Merge documents	POST v1/merge	Client submits a MergeRequest	MergeController.Merge(MergeRequest)	BR-PDFAPI-001, BR-PDFAPI-002, BR-PDFAPI-006, BR-PDFAPI-007, BR-PDFAPI-010, BR-PDFAPI-016, BR-PDFAPI-017, BR-PDFAPI-020
OP-DOWNLOAD-BY-TRACKING-ID	Download by tracking id	GET v1/legacy/download/{trackingId}	Client requests a tracked document	LegacyController.Download(long)	BR-PDFAPI-013, BR-PDFAPI-017
OP-CHECK-TRACKING-STATUS	Check tracking status	GET v1/info/track/{trackingId}	Client polls a tracked request	InfoController.CheckPdfTrackingStatus(long, int, int)	BR-PDFAPI-011, BR-PDFAPI-012, BR-PDFAPI-014
OP-GET-PAGE-COUNT	Get page count	POST v1/info/pages/count	Client submits PDF bytes	InfoController.GetPageCount(byte[])	BR-PDFAPI-005
OP-HAS-FORM-FIELDS	Has form fields	POST v1/info/fields/exist	Client submits PDF bytes	InfoController.HasFormFields(byte[], bool)	BR-PDFAPI-005, BR-PDFAPI-021
OP-FLATTEN-FORM-FIELDS	Flatten form fields	POST v1/info/fields/flatten	Client submits PDF bytes	InfoController.FlattenFormFields(byte[], bool)	BR-PDFAPI-005, BR-PDFAPI-021
OP-IS-PDF	Validate is-PDF	POST v1/info/validate	Client submits arbitrary bytes	InfoController.IsPdf(byte[])	BR-PDFAPI-005
OP-VALIDATE-PDFA	Validate PDF/A conformance	POST v1/info/validate/pdfa	Client submits PDF bytes	InfoController.IsPdfa(byte[])	None catalogued — inspection-only logic
OP-GET-PDF-VERSION	Get PDF version	POST v1/info/version	Client submits PDF bytes	InfoController.Version(byte[])	BR-PDFAPI-005
OP-GET-BUILD-VERSION	Get build version	GET buildVersion	Client requests deployment metadata	ApiInfoController.GetBuildVersionData()	None catalogued — no business logic

Cross-operation flow diagram

The following diagram shows how each of the 13 endpoints routes to its operation and where processor selection, tracking, and download decisions occur.

flowchart TD
    A["Request received"] --> B{"Which endpoint?"}
    B -->|convert| C["OP-CONVERT-REQUEST /<br>OP-CONVERT-FILE"]
    B -->|extract| D["OP-EXTRACT-PAGES"]
    B -->|merge| E["OP-MERGE-DOCUMENTS"]
    B -->|legacy download| F["OP-DOWNLOAD-BY-TRACKING-ID"]
    B -->|info track| G["OP-CHECK-TRACKING-STATUS"]
    B -->|info inspection| H["OP-GET-PAGE-COUNT / OP-HAS-FORM-FIELDS /<br>OP-FLATTEN-FORM-FIELDS / OP-IS-PDF /<br>OP-VALIDATE-PDFA / OP-GET-PDF-VERSION"]
    B -->|buildVersion| I["OP-GET-BUILD-VERSION"]
    C --> J["Processor selected<br>BR-PDFAPI-003"]
    J --> K["Tracking record created/updated"]
    D --> K
    E --> K
    K --> L["Ok result with PdfResult"]
    F --> M{"Status Succeeded and<br>OutputFilePath set?"}
    M -->|Yes| N["Document returned"]
    M -->|No| O["Failure PdfResult, 200 OK"]
    G --> P["Tracking row read; optional poll loop"]
    H --> Q["No tracking, no database<br>pure inspection"]
    I --> R["Build metadata from file system"]

Transaction boundaries

Operation	Unit of work	Commit point	Rollback trigger
OP-CONVERT-REQUEST	IUnitOfWorkFactory("oracle"), InstancePerRequest	PdfTrackingService.CreateTrackingRecord and UpdateTrackingRecord, each bracketed by _uow.Begin()/_uow.Commit()	Unhandled exception before Commit(); NHibernate exception during flush
OP-CONVERT-FILE	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST
OP-EXTRACT-PAGES	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST
OP-MERGE-DOCUMENTS	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST	Same as OP-CONVERT-REQUEST
OP-DOWNLOAD-BY-TRACKING-ID	IUnitOfWorkFactory("oracle"), InstancePerRequest (read-only)	No write — read-only Query() inside Begin()/Commit()	Not applicable — no write occurs
OP-CHECK-TRACKING-STATUS	IUnitOfWorkFactory("oracle"), InstancePerRequest (read-only)	No write — read-only Query() inside Begin()/Commit()	Not applicable — no write occurs
OP-GET-PAGE-COUNT	None	Not applicable — no database access	Not applicable
OP-HAS-FORM-FIELDS	None	Not applicable	Not applicable
OP-FLATTEN-FORM-FIELDS	None	Not applicable	Not applicable
OP-IS-PDF	None	Not applicable	Not applicable
OP-VALIDATE-PDFA	None	Not applicable	Not applicable
OP-GET-PDF-VERSION	None	Not applicable	Not applicable
OP-GET-BUILD-VERSION	None	Not applicable	Not applicable

Failure and edge-case behavior

• Convert, extract, merge, and download failures are caught in the action and returned as a PdfResult with 200 OK — the caller must inspect Status/Message (BR-PDFAPI-017).
• The six v1/info/* byte-array inspection endpoints and v1/info/track/{trackingId} have no try/catch; an unhandled exception (e.g. PdfException for a non-PDF payload) produces framework exception detail (IncludeErrorDetailPolicy.Always) before ApiResponseHandler runs — the final client-visible envelope is unknown** (see Endpoints: Error response shape).
• A null MergeRequest body fails as a framework error, bypassing the per-action envelope entirely (BR-PDFAPI-001).
• An unrecognized convert file extension produces a failure PdfResult whose Status is left at the enum default (NotTracked), not Failed — callers filtering strictly on Status == Failed will miss this case (BR-PDFAPI-008).
• When tracking persistence is unavailable (_uow == null), tracking operations degrade gracefully rather than failing the request (BR-PDFAPI-012).

Related documentation

• API index
• Overview
• Architecture
• Endpoints
• Authentication and authorization
• Dependencies
• Configuration
• Business rules
• Data model
• Operational runbook
• Tech debt

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

• PdfAPI\Controllers\v1\ConvertController.cs
• PdfAPI\Controllers\v1\ExtractController.cs
• PdfAPI\Controllers\v1\MergeController.cs
• PdfAPI\Controllers\v1\LegacyController.cs
• PdfAPI\Controllers\v1\InfoController.cs
• PdfAPI\Controllers\v1\ApiInfoController.cs
• PdfAPI\Services\PdfTrackingService.cs
• PdfAPI\App_Start\IocConfig.cs