Add Smart Endpoints framework for ND API v1 by allenrobel · Pull Request #186 · CiscoDevNet/ansible-nd

allenrobel · 2026-03-03T00:10:21Z

Summary

Adds the Smart Endpoints framework — a type-safe, Pydantic-validated approach to constructing ND REST API endpoint paths and query parameters. This PR is one of three companion PRs targeting nd42_integration:

PR	Branch	Contents	Merge order
#185	`nd42_rest_send`	RestSend framework, `enums.py`, shared test infrastructure	1st
#184	`nd42_logging`	`Log` class and logging config	2nd
This PR	`nd42_smart_endpoints`	Smart Endpoints framework	3rd

Note: Tests depend on enums.py, pydantic_compat.py, and shared test infrastructure from nd42_rest_send (#185), and on log.py from nd42_logging (#184). Tests will not run until all three branches are merged into nd42_integration.

Plugin files added

Base classes (`plugins/module_utils/endpoints/`)

File	Description
`base_path.py`	`ApiPath` — string enum providing type-safe base API path constants shared across all endpoint versions
`endpoint_mixins.py`	Reusable endpoint mixins (e.g. `LoginIdMixin` for endpoints requiring a login ID)
`query_params.py`	`EndpointQueryParams`, `LuceneQueryParams`, `CompositeQueryParams` — Pydantic models for structured, validated query string construction

ND API v1 endpoints (`plugins/module_utils/endpoints/v1/`)

File	Description
`base_paths_infra.py`	Base path constants for the ND `/api/v1/infra` namespace
`base_paths_manage.py`	Base path constants for the ND `/api/v1/manage` namespace
`infra_aaa.py`	AAA (login/logout) endpoints
`infra_clusterhealth.py`	Cluster health endpoints
`infra_login.py`	Login endpoint (`EpInfraLoginPost`) for `/api/v1/infra/login`
`manage_switches.py`	Switch management endpoint with Lucene query support

Unit tests added

File	Covers
`test_base_path.py`	`ApiPath` base class
`test_base_paths_infra.py`	Infra base paths
`test_base_paths_manage.py`	Manage base paths
`test_endpoint_mixins.py`	`LoginIdMixin` and other mixins
`test_endpoints_api_v1_infra_aaa.py`	AAA endpoints
`test_endpoints_api_v1_infra_clusterhealth.py`	Cluster health endpoints
`test_endpoints_api_v1_infra_login.py`	Login endpoint
`test_endpoints_api_v1_manage_switches.py`	Switch management endpoint
`test_query_params.py`	All query parameter models

Dependencies

plugins/module_utils/enums.py — HttpVerbEnum, BooleanStringEnum (from nd42_rest_send Add RestSend framework, enums, and shared unit test infrastructure #185)
plugins/module_utils/pydantic_compat.py — Pydantic shim (from nd42_rest_send Add RestSend framework, enums, and shared unit test infrastructure #185)
tests/unit/module_utils/common_utils.py — does_not_raise() (from nd42_rest_send Add RestSend framework, enums, and shared unit test infrastructure #185)

Merge order

Merge nd42_rest_send (Add RestSend framework, enums, and shared unit test infrastructure #185) → nd42_integration
Merge nd42_logging (Add Log class and logging config #184) → nd42_integration
Merge this PR → nd42_integration

Test plan

After merging all three PRs into nd42_integration: python -m pytest tests/unit/module_utils/endpoints/ passes cleanly
tox -e linters passes (black, isort, pylint, mypy)
ansible-test sanity --docker passes

🤖 Generated with Claude Code

Base classes: - plugins/module_utils/ep/base_path.py: ApiPath base class for type-safe endpoint path construction - plugins/module_utils/ep/base_paths_ndfc.py: NDFC base path constants - plugins/module_utils/ep/endpoint_mixins.py: Reusable endpoint mixins (e.g. LoginIdMixin) - plugins/module_utils/ep/query_params.py: EndpointQueryParams, LuceneQueryParams, CompositeQueryParams for structured query string building ND API v1 endpoints: - plugins/module_utils/ep/v1/base_paths_infra.py: Infra API base paths - plugins/module_utils/ep/v1/base_paths_manage.py: Manage API base paths - plugins/module_utils/ep/v1/ep_infra_aaa.py: AAA (login) endpoint - plugins/module_utils/ep/v1/ep_infra_clusterhealth.py: Cluster health endpoint - plugins/module_utils/ep/v1/ep_manage_switches.py: Switch management endpoint Design documentation: - plugins/module_utils/ep/ANALYSIS_COMPLEXITY.md - plugins/module_utils/ep/ANALYSIS_ENDPOINT_DESIGN.md - plugins/module_utils/ep/ANALYSIS_TYPE_SAFETY.md Unit tests: - tests/unit/module_utils/ep/test_base_path.py - tests/unit/module_utils/ep/test_base_paths_infra.py - tests/unit/module_utils/ep/test_base_paths_manage.py - tests/unit/module_utils/ep/test_endpoint_mixins.py - tests/unit/module_utils/ep/test_ep_api_v1_infra_aaa.py - tests/unit/module_utils/ep/test_ep_api_v1_infra_clusterhealth.py - tests/unit/module_utils/ep/test_ep_api_v1_manage_switches.py - tests/unit/module_utils/ep/test_query_params.py Note: tests depend on enums.py, pydantic_compat.py, and shared test infrastructure (common_utils, etc.) from nd42_rest_send, and on log.py from nd42_logging. Tests will not run until all branches are merged into nd42_integration. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

plugins/module_utils/ep/ANALYSIS_COMPLEXITY.md

plugins/module_utils/ep/base_paths_ndfc.py

mtarking · 2026-03-03T12:31:24Z

plugins/module_utils/ep/endpoint_mixins.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+


Would like to discuss this in the standup today

Yes, this is a holdover from Python v2 and is no longer needed in v3. If non-ASCII character accidentally made its way into a Python v2 file, you'd get a SyntaxError exception without it (though, I'd argue that would be a good thing).

Anyway, I'll remove these from all the files in my PRs.

Removed from all files in this PR. Need to do the same for the other PRs.

plugins/module_utils/ep/base_path.py

plugins/module_utils/ep/query_params.py

plugins/module_utils/endpoints/v1/__init__.py

1. Remove /mso, /appcenter/*, /login paths TODO: Need to add /api/v1/infra/login under infra endpoints.

Removed the following from all files: # -*- coding: utf-8 -*-

- plugins/module_utils/ep/ → plugins/module_utils/endpoints/ - v1/ep_infra_aaa.py → v1/infra_aaa.py - v1/ep_infra_clusterhealth.py → v1/infra_clusterhealth.py - v1/ep_manage_switches.py → v1/manage_switches.py - tests/unit/module_utils/ep/ → tests/unit/module_utils/endpoints/ - test_ep_api_v1_*.py → test_endpoints_api_v1_*.py - Update all internal imports to reflect new paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replaces the test_ep_ prefix in all test function names within the three ep-specific test files to match the renamed file and directory. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ansible sanity tests use a regex to verify the __metaclass__ = type declaration and do not expect an inline comment. Move the pylint disable/enable directives to separate lines. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lhercot · 2026-03-04T13:57:04Z

plugins/module_utils/endpoints/mixins.py

@@ -0,0 +1,89 @@
+# Copyright: (c) 2026, Allen Robel (@arobel) <arobel@cisco.com>


do we need endpoint_ in this name can be mixins.py

Akshay has mixins and others will have mixins so should we put them all in onen file called mixins.py or only put "common" things in mixins.py and use a module_name directory or some other way to separate mixin files?

Renamed to mixins.py with commit: 26cbd52

Endpoint mixins are associated with endpoints rather than than modules. So, I'd lean toward keeping them in one file (or, if we use multiple files, name them e.g. infra_mixins.py, manage_mixins.py, etc). I had Claude do an analysis of the query parameter usage in infra and manage where he read the schema and reported on the percentage sharing of query params across all endpoints, max query params used by endpoints, etc.

Claude found zero overlap between infra and manage, so these should probably be separate files:

https://github.com/CiscoDevNet/ansible-nd/blob/rest_send_integration/ANALYSIS_ENDPOINT_PARAMETERS.md

Another conclusion Claude made is that there are several mixins defined in mixins.py that are not used in either infra or manage schemas. These are probably legacy mixins from NDFC, so I'll open an issue to remove them. I'll double check these though...

"Key Finding: Only 3 of 11 defined mixins are actually used (LoginIdMixin, FabricNameMixin, ForceShowRunMixin). The 8 unused mixins (ClusterNameMixin, HealthCategoryMixin, InclAllMsdSwitchesMixin, LinkUuidMixin, NetworkNameMixin, NodeNameMixin, SwitchSerialNumberMixin, VrfNameMixin) have no corresponding parameters in either schema."

mikewiebe · 2026-03-04T18:43:40Z

plugins/module_utils/endpoints/v1/manage_switches.py

@@ -0,0 +1,178 @@
+# Copyright: (c) 2026, Allen Robel (@arobel) <arobel@cisco.com>
+
+# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)


Remove this file

mikewiebe · 2026-03-04T18:45:48Z

plugins/module_utils/endpoints/__init__.py

+
+## Current Stable API Version
+
+v1 (ND 3.0+, NDFC 12+)


Update to be ND 4.2+, Remove NDFC reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

pydantic_compat was moved into module_utils/commmon in nd42_rest_send branch. nd42_smart_endpoints and nd42_rest_send will be merged into a common integration branch shortly, so am updating at least some of the imports that are known to have changed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Forgot to add this in the earlier commit.

typing.Final was added in Python 3.8. Since all affected files already use from __future__ import annotations (PEP 563), Final is only needed during static type checking and never evaluated at runtime. Guarding the import with TYPE_CHECKING avoids the ImportError on Python 3.7 with no dependency on typing_extensions. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adding for Ansible sanity tests.

Literal was added in Python 3.8. ansible-test sanity runs against Python 3.7, so importing it directly causes ImportError. Since all three files already have `from __future__ import annotations`, all annotations are lazy strings at runtime and the TYPE_CHECKING guard is safe. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ansible-test sanity requires all __init__.py files under plugins/ to be completely empty. No imports are broken since all consumers already import directly from submodules. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

allenrobel requested review from akinross, anvitha-jain, gmicol, lhercot, sajagana, samiib and shrsr as code owners March 3, 2026 00:10

mikewiebe reviewed Mar 3, 2026

View reviewed changes

plugins/module_utils/ep/ANALYSIS_COMPLEXITY.md Outdated Show resolved Hide resolved

mikewiebe reviewed Mar 3, 2026

View reviewed changes

plugins/module_utils/ep/base_paths_ndfc.py Outdated Show resolved Hide resolved

mtarking requested changes Mar 3, 2026

View reviewed changes

mikewiebe reviewed Mar 3, 2026

View reviewed changes

plugins/module_utils/endpoints/v1/__init__.py Outdated Show resolved Hide resolved

allenrobel and others added 10 commits March 3, 2026 07:30

Remove analysis files

9e59bb7

Remove NDFC base paths

f4b866a

Remove legacy endpoint paths

c04265f

1. Remove /mso, /appcenter/*, /login paths TODO: Need to add /api/v1/infra/login under infra endpoints.

Remove legacy source file encoding declaration

c9f7725

Removed the following from all files: # -*- coding: utf-8 -*-

Remove one more stray file with legacy declaration

f6def76

Rename test function names: test_ep_ → test_endpoints_

ad78100

Replaces the test_ep_ prefix in all test function names within the three ep-specific test files to match the renamed file and directory. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix linter formatting to use 159 character line length

73c2f9c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add EpInfraLoginPost endpoint for /api/v1/infra/login

f608531

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

lhercot reviewed Mar 4, 2026

View reviewed changes

mikewiebe reviewed Mar 4, 2026

View reviewed changes

allenrobel and others added 5 commits March 4, 2026 08:50

Remove references to ND 3.0 and NDFC

e8207e4

Rename endpoint_mixins.py to mixins.py and update imports

26cbd52

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Update all pydantic_compat imports

cd52a87

pydantic_compat was moved into module_utils/commmon in nd42_rest_send branch. nd42_smart_endpoints and nd42_rest_send will be merged into a common integration branch shortly, so am updating at least some of the imports that are known to have changed.

Remove manage_switches endpoint and tests (moved to teammate branch)

94fea53

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Import pydantic_compat from module_utils/common

1484c62

Forgot to add this in the earlier commit.

allenrobel and others added 5 commits March 5, 2026 09:55

Add tests/sanity/config.yml

2fd322c

Adding for Ansible sanity tests.

Move config.yml under tests/

ac20b5b

		@@ -0,0 +1,89 @@
		# Copyright: (c) 2026, Allen Robel (@arobel) <arobel@cisco.com>

		@@ -0,0 +1,178 @@
		# Copyright: (c) 2026, Allen Robel (@arobel) <arobel@cisco.com>

		# GNU General Public License v3.0+ (see LICENSE or https://www.gnu.org/licenses/gpl-3.0.txt)

Conversation

allenrobel commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Plugin files added

Base classes (plugins/module_utils/endpoints/)

ND API v1 endpoints (plugins/module_utils/endpoints/v1/)

Unit tests added

Dependencies

Merge order

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

allenrobel Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

allenrobel commented Mar 3, 2026 •

edited

Loading

Base classes (`plugins/module_utils/endpoints/`)

ND API v1 endpoints (`plugins/module_utils/endpoints/v1/`)

allenrobel Mar 5, 2026 •

edited

Loading