# API and Asset Version Compatibility

*MuleSoft Platform Architect Study Guide · Designing and sharing APIs · Last updated November 13, 2026 · https://www.certifyforce.com/study-guide/mulesoft-platform-architect/designing-and-sharing-apis/api-and-asset-version-compatibility*

Classify API changes by their effect on existing consumers, then keep the contract version and Exchange asset release consistent. Review behavior, data, representations and access as well as schemas.

- Certification: Salesforce MuleSoft Platform Architect
- Exam section: Designing and sharing APIs
- Study guide: https://www.certifyforce.com/study-guide/mulesoft-platform-architect

**Official exam objective:**

> Identify changes to an API that would require or not require changing the major/minor/patch component of its semantic version.

## What the exam expects

- Classify breaking changes, compatible additions and compatible corrections.
- Evaluate operation effects and response-value domains alongside data shapes.
- Distinguish an API version from an Exchange asset version.
- Recognize representation and permission changes that affect consumers.
- Preserve usable consumer documentation across an API's evolution.

**Compatibility** means an existing consumer can continue without adaptation; **major**, **minor** and **patch** identify release components; an **API version** identifies a contract line; an **asset version** identifies a published Exchange release.

## Key facts

| Fact | Detail | Source |
|---|---|---|
| Major | Existing consumers must adapt to the incompatible contract. | [Classification](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Minor | Adds capability while preserving existing consumers. | [Classification](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Patch | Compatible bug fix or documentation update. | [Classification](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Operation effect | Changing it is a major service-contract change. | [Service contract](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Response type | A changed type requires a major version. | [Service contract](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Permissions | Restricting existing access requires a major change. | [Accessibility](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Version pairing | Compatible minor/patch specification releases retain the API version. | [Version relationship](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Shared presentation | Name, icon and description edits span all versions. | [Presentation](https://docs.mulesoft.com/exchange/to-change-raml-version) |
| Documentation | Pages can differ by minor asset version. | [Documentation](https://docs.mulesoft.com/exchange/to-change-raml-version) |

## Check yourself

- Why can changing an asset icon affect releases other than the one an editor is viewing?
- When editing consumer documentation for a particular minor asset version, which selector establishes the intended scope?
- Which semantic-version syntax feature is unavailable for Exchange asset releases?

## Sources

- [Changing the Version of an API Asset](https://docs.mulesoft.com/exchange/to-change-raml-version)

## About the full unit

The "Core concepts", "Exam traps" and "Worked scenario" sections of this unit, its 6 linked practice questions, and unlimited timed mock exams are included with the MuleSoft Platform Architect pack (USD $19): https://www.certifyforce.com/practice-exams