MPT-19903: add /integration/extensions/{id}/instances service

[albertsola]

Summary

Implements the /public/v1/integration/extensions/{extensionId}/instances endpoint group as part of MPT-13310.

Changes

• mpt_api_client/resources/integration/extension_instances.py — CreateMixin + GetMixin + CollectionMixin
• Updated extensions.py to expose instances(extension_id) accessor
• Unit tests: tests/unit/resources/integration/test_extension_instances.py
• E2e tests: tests/e2e/integration/extension_instances/

Depends on

#277 (MPT-19892 — rename extensibility → integration)

⚠️ Draft — targets MPT-19892/e2e-extension-base-service until PR #277 merges.

Closes MPT-19903

• Implements the /public/v1/integration/extensions/{extensionId}/instances endpoint group
• Adds ExtensionInstance model with attributes for identity, relationships, and state
• Introduces ExtensionInstancesService and AsyncExtensionInstancesService with create, get, and list operations
• Exposes instances(extension_id) accessor methods on both synchronous and asynchronous extensions services
• Adds unit tests covering service mixins, model field mapping, and accessor methods
• Adds end-to-end integration tests for both sync and async workflows (create, filter, and get operations)
• Updates e2e configuration with extension instance identifier mapping

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds comprehensive support for managing extension instances as a sub-resource within the extensions API. It introduces the ExtensionInstance data model, synchronous and asynchronous service implementations, integration with the parent ExtensionsService, and both unit and end-to-end test coverage.

Changes

Extension Instances Feature

Layer / File(s)	Summary
Data Model & Service Configuration mpt_api_client/resources/integration/extension_instances.py	Defines ExtensionInstance model with typed fields (id, name, revision, external_id, status, extension, meta, channel, audit) and ExtensionInstancesServiceConfig binding to the /public/v1/integration/extensions/{extension_id}/instances endpoint.
Sync/Async Service Implementation mpt_api_client/resources/integration/extension_instances.py	Implements ExtensionInstancesService (sync) and AsyncExtensionInstancesService (async) composed from create/get/list mixins, both parameterized with ExtensionInstance.
Extensions Service Integration mpt_api_client/resources/integration/extensions.py	Adds instances(extension_id: str) methods to ExtensionsService and AsyncExtensionsService that instantiate and return the corresponding instance service configured with the provided extension ID.
E2E Test Configuration & Fixtures e2e_config.test.json, tests/e2e/integration/extension_instances/conftest.py	Adds test instance ID configuration and pytest fixtures for instance ID, service accessors (sync/async), and instance payload data.
Unit Tests tests/unit/resources/integration/test_extension_instances.py	Validates model field mapping, service mixin presence, create/iterate operations via mocked HTTP, and accessor methods on both sync and async extensions services.
E2E Tests (Sync) tests/e2e/integration/extension_instances/test_sync_extension_instances.py	E2E integration tests for synchronous API: create (skipped), filter/iteration, and get operations, all marked as flaky.
E2E Tests (Async) tests/e2e/integration/extension_instances/test_async_extension_instances.py	E2E integration tests for asynchronous API: async create (skipped), filter/iteration, and get operations, all marked as flaky.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• softwareone-platform/mpt-api-python-client#285: Adds .media(...) accessor method to ExtensionsService/AsyncExtensionsService in the same file.
• softwareone-platform/mpt-api-python-client#282: Implements analogous sub-resource service and accessor methods for "installations" on the same extensions service classes.
• softwareone-platform/mpt-api-python-client#284: Adds a new integration sub-resource module and accessor methods on ExtensionsService/AsyncExtensionsService for "documents".

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Jira Issue Key In Title	✅ Passed	✅ Found Jira issue key in the title: MPT-19903
Test Coverage Required	✅ Passed	PR modifies 3 code files (extension_instances.py, extensions.py, e2e_config.test.json) and includes comprehensive test coverage with 4 test files: unit tests, E2E sync/async tests, and test fixtures.
Single Commit Required	✅ Passed	PR contains exactly 1 commit (ed5bcd7). Single commit requirement satisfied.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

🧹 Nitpick comments (1)

tests/e2e/integration/extension_instances/test_sync_extension_instances.py (1)

10-14: ⚡ Quick win

Consider using xfail instead of hard skip for known backend issues.

Line 10 uses skip which hides the test completely; using xfail(strict=False) keeps the test visible and will surface when the backend issue is fixed. Apply the same change in the async counterpart too. Replace the placeholder with an actual issue ticket ID for tracking.

Proposed change

-@pytest.mark.skip(reason="returns 500 error")
+@pytest.mark.xfail(
+    reason="Known backend 500 for create extension instance (link issue ID)",
+    strict=False,
+)
 def test_create_extension_instance(extension_instances_service, instance_data):

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/e2e/integration/extension_instances/test_sync_extension_instances.py`
around lines 10 - 14, Replace the hard skip on the failing test by marking it
xfail so it still runs and will surface when fixed: remove pytest.mark.skip on
test_create_extension_instance and use
pytest.mark.xfail(reason="BACKEND-<ISSUE_ID>: returns 500 error", strict=False)
instead; apply the same change to the async counterpart test (the async test
that uses extension_instances_service and instance_data) so both tests remain
visible while tracking the backend ticket ID.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/e2e/integration/extension_instances/test_sync_extension_instances.py`:
- Around line 10-14: Replace the hard skip on the failing test by marking it
xfail so it still runs and will surface when fixed: remove pytest.mark.skip on
test_create_extension_instance and use
pytest.mark.xfail(reason="BACKEND-<ISSUE_ID>: returns 500 error", strict=False)
instead; apply the same change to the async counterpart test (the async test
that uses extension_instances_service and instance_data) so both tests remain
visible while tracking the backend ticket ID.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 58c3f5cf-1438-4178-9434-2f11999ac446

📥 Commits

Reviewing files that changed from the base of the PR and between c61b7b9 and ed5bcd7.

📒 Files selected for processing (8)

• e2e_config.test.json
• mpt_api_client/resources/integration/extension_instances.py
• mpt_api_client/resources/integration/extensions.py
• tests/e2e/integration/extension_instances/__init__.py
• tests/e2e/integration/extension_instances/conftest.py
• tests/e2e/integration/extension_instances/test_async_extension_instances.py
• tests/e2e/integration/extension_instances/test_sync_extension_instances.py
• tests/unit/resources/integration/test_extension_instances.py