Practical guides · Practical guide

GxP API version changes: testing mappings and error handling

An API may still respond successfully after a version change while the receiving system misinterprets a new status or unit. Test the meaning and agreed structure of the exchanged data as well as endpoint availability.

Table of contents

At a glance

What should you test when an API version changes in GxP operation?

Assess changes in structure, meaning, units, status rules, authentication and error handling against the intended process. Test critical mappings against known expected results, including the final state in the receiving application. Include missing, duplicate, late and rejected messages. A technical success response does not prove complete business processing.

Draft the technical data agreement

An API agreement encompasses more than just field names. Document the professional meaning of a message, identify the leading system, and define when a process is considered complete. Describe object identity, data types, units, allowed states, and required relationships. A field "status" may, for example, indicate inspection status, transmission status, or business release. These interpretations must not be inadvertently mixed during version changes.

Define the system boundary. This may include components such as the Quellan application, API gateway, integration service, mapping, and target process. Testing of the gateway alone does not validate the processing within the target system. Capture the actually used API versions and customer-specific transformations. The vendor's designation of a "compatible update" serves as input for evaluation but does not constitute automatic confirmation that each individual process continues to operate correctly.

Sources: [1] [2]

Evaluate changes based on significance rather than solely on schema.

Compare old and new definitions. New mandatory fields, different data types, and removed values are obvious candidates. Similarly relevant are unchanged field names with altered meaning: quantity now in a different unit, timestamp with a new reference point, or an additional status value. A formally valid JSON can be incorrectly interpreted from a domain perspective. Therefore, a relevance review requires knowledge of the actual end-user process.

Evaluate apparent additive changes as well. A new optional field may leave existing processing unaffected; a new enum value, however, could result in an incomplete case distinction. An altered sorting or page size may affect the completeness of a query. Document which changes are involved and justify why additional evidence is no longer required. A simple list of modified endpoints does not adequately address the impact of these changes.

Sources: [1]

Example: a unit changes

In the example, Version 1 transfers a result value of 9.8 with the unit mg. Version 2 provides the same numerical value as 0.0098 g. The target must still be evaluated as 9.8 mg according to the established rule. A parser that only captures the numeric value generates a seemingly plausible but incorrect result. The independently calculated required value is documented prior to testing.

The new version introduces the status "pending_review". In the example, this state must not be considered as approved. Verify the specific assignment and an unknown future value. The appropriate response is derived from the process itself, for example, suspension with responsible clarification. The matrix below serves as an independent work aid. It does not claim to represent a universal API convention nor does it prescribe a general technical handling of any unknown field.

Assessing the impact of an API version change
ChangeTechnical RiskTargeted evidence
mg to g Incorrect magnitude Independent unit conversion
New status Unauthorized further processing Allowed and unknown values
Field is optional Incomplete recordkeeping Missing and blank value
New page width Incomplete population Several pages with known inventory on hand
Alternative time reference Incorrect event sequence Compare source and target time points
New error response Unclear partial state Interruption and controlled restart

Sources: [1]

Check syntax, mapping, and target state separately

A structural and type validation test verifies the structure and allowed types. A mapping validation test checks the technical and functional alignment. A process validation test confirms that the intended target state has been achieved. These layers complement each other. A test that only expects a successful HTTP status may overlook erroneous data storage. Therefore, relevant target objects and relationships should be validated using appropriate authorized access rights.

Use established reference messages and independent setpoints. Verify numerical values, date formats, leading zeros, special characters, and empty values where they impact the process. Maintain consistent source and target identity. Any manual correction during testing must be documented and shall not be presented as an unaltered interface result. If a test tool itself transforms data, its role must be clearly understood within the validation evidence.

Sources: [1] [2]

Verify repetition, sequence, and partial reprocessing

Power outages can create an ambiguous state: the client receives no response, even though the target has already processed the request. Define how repetition is detected and handled. Retransmission must not result in an undetected duplicate processing. The specific procedure depends on the API agreement and internal design. A technical request ID alone does not prove that the target operation is functionally idempotent.

Review delayed and swapped messages. An older status may not override a newer one uncontrolled if the process rule explicitly excludes this. In batch processing, some data sets may be successfully processed while others may be rejected. Define how these partial states are made visible and further handled. A global "job completed" is insufficient as evidence that each relevant record has been fully and accurately received.

Sources: [1]

Evaluate access and logging during version changes.

A new version may employ different authorizations, technical identities, or authentication methods. Verify the actually required access and revoke outdated authorizations following the controlled handover. Test an unauthorized action and the availability of required functions for the intended role. A successfully authenticated technical user is not automatically authorized for every data access.

Determine the required evidence for technical processing and professional changes. Interface logs, business documents, and audit trails may provide different information. A message containing confidential content must not be arbitrarily duplicated without appropriate protection and retention decisions. Document in such a way that errors and affected objects are reconstructible. The exact scope shall be determined by process, risk, and the required historical traceability.

Sources: [1] [2]

Plan transition and rollback in advance

Define whether old and new versions will be used concurrently during a transition period. Assess which data are processed in what format and how open activities are managed. A rollback may be challenging if the new version has already generated data that the old version cannot interpret. Evaluate this limitation prior to the transition. The technical availability of an older endpoint does not constitute a complete technical and professional rollback plan.

Plan the cut-off, the last old message, the first new message, and the subsequent reconciliation. Verify the relevant population and known edge cases. After transition, obsolete connections and accesses will be terminated to the extent of release. Avoid an undefined parallel operation that processes the same process via two pathways. Required productivity checks will be defined in advance and complement the testing conducted in an appropriate environment.

Sources: [1]

Regression and operational responsibility retained

The closure ties together changes, affected requirements, verified message types, results, and corrective actions. Explicitly define boundaries. Verification of result transmission does not automatically validate all master data or recall notifications for the same API. Utilize a controlled collection of critical reference cases that can be reused after relevant changes. It must be professionally maintained, not merely technically sustainable.

Determine responsible persons for API contract, mapping, error editing and professional comparison. New status values, data fields or deprecation notes need a regulated input into the change evaluation. The actual quality lies in the permanently comprehensible context of source and target. A green accessibility test and a long log file can support this proof, but do not replace it.

Sources: [1]

Project experience and collaboration

Check changed API responses against the actual state of the target system

Before an API change, IT and process owners compare old and new messages for selected business transactions, including changes to units, statuses and error responses. We examine what the target system actually received and processed. A small change may need a few focused comparisons. A redesigned data structure may warrant phased transition with outputs compared in parallel. We include repeated, missing and delayed messages in the plan.

Frequently asked questions about API changes and validation

Must a new API version always be fully revalidated?

Assess the specific change and its impact. Relevant data pathways, functions, and risks require appropriate validation evidence. Stable areas may be addressed differently with a justified rationale. A comprehensive end-to-end test is not always necessary; a test exemption solely based on claimed compatibility is insufficient.

Does an HTTP 200 response constitute a successful validation test?

No. A technical success response may, depending on the contract, only confirm receipt or a processing step. Verify the required professional data retention and the correct target state. For asynchronous workflows, later processing and error handling are additionally considered. Acceptance criteria must cover the actual process intent.

Can new optional fields affect existing processes?

Yes, depending on implementation and significance. Additional status values, alternative sorting, or page sizes may affect existing assumptions. Assess the data processing agreement and your own data handling procedures. Not every additional change is critical, but the non-impact of such changes should be clearly justified.

What should be verified upon repetitions following a timeout?

Whether the first attempt has already been professionally processed and how a subsequent message is handled. Check for duplicate processing, identity assignment, and achievable target state. The appropriate procedure depends on the specific API design. Blind repetition may introduce additional errors in cases of partial processing.

Do permissions relate to API change assessment?

Yes, to the extent that the changes affect them or influence the required functions. Verify technical identity, permitted scope, and rejected actions. Controlled revocation of old access rights is part of the transition. Authentication alone does not establish appropriate authorization for all data and functions.

When is a recurrence truly possible?

If the existing pathway continues to correctly process the required data and outstanding activities, and a return is verified or adequately justified, new data formats may limit this capability. Define triggers, responsible parties, and reconciliation procedures. The mere existence of an old endpoint is insufficient.

Sources and review date

Status: October 14, 2026. Regulatory classification is based on the cited original sources. Examples and test matrices are internal support tools; they are adapted for actual usage purposes.

  1. European Commission: EU GMP Annex 11, Computerised Systems (2011)Current version as listed in the EudraLex directory as of 14.10.2026. Application, risks, operation, and data lifecycle; specific testing proposals are derived independently. For the testing questions addressed, Annex 11 sections 4.7 (test methods and error handling), 5 (data exchange), and 10 (changes) are particularly relevant. The specific change matrix is a separate work aid.
  2. PIC/S: PI 041-1, Good Practices for Data Management and Integrity (2021)Inspection Guidance on Data Integrity; in particular electronic data, transmission, access, and review.

Sources checked: .

Daniel Herrmann, Daniel Herrmann Consulting

Daniel Herrmann Consulting

How we can support you

Daniel Herrmann Consulting combines professional assessment with hands-on work on the specific system. During the first meeting, we clarify your intended use, existing documentation, and the next most appropriate action step.

  • Computer system validation →

    Bring your GxP systems into validated operation, from laboratory software, MES and eQMS to ERP. We define the scope, plan risk-based tests using GAMP 5 and hand the evidence to QA for release.

Send a project enquiry Customer testimonials →