# Backwards Compatibility

We've designed the Hyp API with backwards compatibility as a core principle. This means that when you build an integration with our XML-based APIs, you can trust that your implementation will continue working smoothly as we add new features and improvements to the platform.

{% hint style="info" %}
**Note**: Backwards compatibility applies to all XML-based API endpoints, including `doDeal`, `getCardId`, `inquireTransactions`, and other commands documented in the [API Reference](/enterprise/api-reference/index.md).
{% endhint %}

## What we promise

Here's what you can count on from the Hyp API to keep your integration stable:

### Request field stability

* **Existing request fields will always work** - we won't remove any fields from API endpoints
* **New fields are always optional** - when we add new functionality, you don't need to update your existing code
* **Field names and data types remain unchanged** - no surprises with format changes

### Response field stability

* **Response fields you rely on will remain** - we won't remove fields from API responses
* **Field values keep their current format** - your parsing logic will continue to work
* **New response fields may be added** - but they won't interfere with your existing code

### Data value consistency

* **Values will stay consistent** - we won't change or remove existing field values
* **Enumerated values are stable** - new options may be added, but existing ones won't change
* **Response codes and messages retain their meaning** - a "000" success code will always indicate success

## How to build a future-proof integration

To ensure your integration remains reliable as we enhance the platform, we recommend following these practices:

### XML response handling

* **Handle additional fields gracefully** - your code should continue working when new response fields are added
* **Use defensive XML parsing** - ignore fields you don't recognize instead of throwing errors
* **Support new values in existing fields** - be flexible when new options are added to enumerated fields

### Integration best practices

* **Choose flexible XML parsing libraries** - select ones that won't break when encountering unknown elements
* **Build forgiving field validation** - validate what you need, but don't fail on unexpected data
* **Test regularly in sandbox** - try out new API versions before deploying to production

{% hint style="warning" %}
**Heads up**: If your parsing logic is too strict, you might run into issues when new fields or values are added. We recommend testing your integration with the latest API versions to catch potential issues early.
{% endhint %}

## Implementation examples

### Defensive XML parsing

Here's how to ensure your code can handle additional fields when they are added:

```xml
<!-- Your existing parsing logic should handle this gracefully -->
<ashrait>
  <response>
    <command>doDeal</command>
    <result>000</result>
    <message>Transaction approved</message>
    <!-- New fields may appear here -->
    <newFeature>enabled</newFeature>
    <enhancedSecurity>true</enhancedSecurity>
  </response>
</ashrait>
```

### Field validation

Here are two approaches to validation — one that's flexible and future-friendly, and one to avoid:

```javascript
// Good: Flexible validation that allows new fields
function validateResponse(response) {
  const requiredFields = ['command', 'result', 'message'];
  
  for (const field of requiredFields) {
    if (!response[field]) {
      throw new Error(`Missing required field: ${field}`);
    }
  }
  
  // Allow additional fields without validation errors
  return true;
}

// Avoid: Strict validation that fails on new fields
function validateResponseStrict(response) {
  const allowedFields = ['command', 'result', 'message'];
  
  for (const field in response) {
    if (!allowedFields.includes(field)) {
      throw new Error(`Unexpected field: ${field}`); // This will break with new fields
    }
  }
  
  return true;
}
```

## Testing and validation

### Sandbox environment testing

* **Test regularly with the latest versions** – this helps you catch any compatibility issues early
* **Check for new fields in responses** – make sure they don't break your parsing logic
* **Try different response scenarios** – test both success and error cases

### Production deployment

* **Time your deployments wisely** – consider deploying during quieter periods
* **Keep an eye on your logs** – monitor closely after any API-related changes
* **Have a backup plan** – be ready to roll back if something unexpected happens

## Related documentation

For more information about API integration and best practices, see:

* [API Request & Response General Structure](/enterprise/introduction/request-and-response-general-structure.md)
* [Authentication and Security](/enterprise/introduction/authentication-and-security.md)
* [API Reference](/enterprise/api-reference/index.md)

Following these guidelines will help ensure your integration stays stable and reliable as we continue to improve and expand the Hyp platform.

If you have questions about compatibility or need help with your integration, please [reach out to the Hyp support team](mailto:cg-support@hyp.co.il).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hyp.co.il/enterprise/advanced-considerations/backwards-compatibility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.