Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv #893

ahouseholder · 2025-08-20T16:12:19Z

resolves Add FastAPI for Registry #894
resolves Incorporate uv into our build process #895

This PR:

Adds a dockerized FastAPI REST interface for the registry object from Refactor registry construction #844
Starts using uv to manage the pyproject.toml, which allows us to consolidate our package and virtual environment management into one place. requirements.txt can now be dumped from pyproject.toml.
Updates docker specs to use uv in the build process

To try the api:

make api_dev (local with live reload) or make api (docker)
navigate to localhost:8000 for api_dev or localhost:8001 for api

You can also do make up and assuming docker is installed it will run three containers:

unit tests
docs (8000)
api (8001)

Copilot Summary as of `1062ba9`

This pull request introduces several significant improvements to the project, focusing on modernizing dependency management, enhancing development workflows, and adding a new API for the SSVC registry. The changes migrate the build and test systems to use uv for Python dependency and environment management, update Docker and Makefile workflows for consistency, and introduce a FastAPI-based API for accessing SSVC decision points and tables. Additionally, a new decision point group is added, and schema examples are updated for clarity.

Development and Build System Modernization:

Migrated Python dependency management and environment setup from pip and requirements files to uv, updating all relevant CI workflows (.github/workflows/link_checker.yml, .github/workflows/python-app.yml), the Makefile, and Dockerfiles to use uv sync and uv run for installing dependencies and running commands. This streamlines development, testing, and documentation processes. [1] [2] [3] [4] [5]
Updated the minimum required Python version to 3.12 and pinned all dependencies in src/pyproject.toml, ensuring reproducible builds and compatibility with the new tooling. Added a [dependency-groups] section for development dependencies. [1] [2] [3]

Docker and Makefile Enhancements:

Refactored Dockerfiles and docker-compose.yml to add a dedicated api service for the new registry API, improved build caching, and ensured that all services consistently use the new dependency management approach. Added and updated Makefile targets for local and Docker-based development, testing, and documentation workflows. [1] [2] [3] [4]
Added a .dockerignore file to exclude unnecessary files and directories from Docker build context, improving build performance and security.

API Addition:

Introduced a new FastAPI-based API for the SSVC registry, including the main application (src/ssvc/api/main.py), module initialization (src/ssvc/api/__init__.py), and helper functions (src/ssvc/api/helpers.py). The API exposes endpoints for decision points, tables, types, namespaces, and more, and is integrated into Docker and Makefile workflows. [1] [2] [3]

Data and Schema Updates:

Added a new decision point group JSON file for "theParanoids" prioritized risk remediation (data/json/decision_points/x_com_yahooinc_prioritized_risk_remediation/theparanoids_1_0_0.json).
Updated example values in multiple JSON schema files to more accurately reflect extension and localization patterns. [1] [2] [3] [4] [5] [6]

# Conflicts: # docker/Dockerfile

… feature/fastapi

…stapi

ahouseholder · 2025-08-20T16:58:09Z

I intend to add /*/{namespace}/{key}/latest too, just haven't got to it yet.

ahouseholder · 2025-08-21T20:18:22Z

Path	Methods	Response Model	Description
/decision_point/	GET	DecisionPoint	Returns a single DecisionPoint object by its ID.
/decision_points/	GET	DecisionPointDictResponse	Get all decision points
/decision_points/{namespace}	GET	DecisionPointDictResponse	Get all decision points for a namespace
/decision_points/{namespace}/{key}	GET	DecisionPointDictResponse	Get all versions of a decision point for a key in a namespace
/decision_points/{namespace}/{key}/latest	GET	DecisionPoint	Get the latest decision point for a key in a namespace
/decision_points/{namespace}/{key}/{version}	GET	DecisionPoint	Get a specific version of a decision point
/decision_points/{namespace}/{key}/latest/values	GET	DecisionPointValueListResponse	Get the latest decision point for a key in a namespace
/decision_points/{namespace}/{key}/{version}/values	GET	DecisionPointValueListResponse	Get the values of a decision point
/decision_table/	GET	DecisionTable	Returns a single DecisionTable object by its ID.
/decision_tables/	GET	DecisionTableDictResponse	Get all decision tables
/decision_tables/{namespace}	GET	DecisionTableDictResponse	Get decision tables for a namespace
/decision_tables/{namespace}/{key}	GET	DecisionTableDictResponse	Get decision tables for namespace and key
/decision_tables/{namespace}/{key}/latest	GET	DecisionTable	Get the latest decision table for a namespace and key
/decision_tables/{namespace}/{key}/{version}	GET	DecisionTable	Get a specific version of a decision table
/objtypes/	GET	TypesDictResponse	Get all object types
/objtypes/list	GET	ListOfStringsResponse	Retrieve a list of available object types
/namespaces/	GET	NamespaceDictResponse	Get all object types and their namespaces
/namespaces/list	GET	ListOfStringsResponse	Get a list (without the enclosing dict) of all namespaces in the registry (regardless of object type)
/namespaces/{objtype}	GET	NamespaceDictResponse	Get the namespaces in the registry for a given object type
/namespaces/{objtype}/list	GET	ListOfStringsResponse	Get a list of namespaces for a given object type
/keys/	GET	KeyDictResponse	Get Key Dictionary
/keys/{objtype}	GET	KeyDictResponse	Get Key Dictionary for Type
/keys/{objtype}/{namespace}	GET	KeyDictResponse	Get Key Dictionary for Type and Namespace
/keys/{objtype}/{namespace}/list	GET	ListOfStringsResponse	Get Key Dictionary for Type and Namespace
/versions/{objtype}/{namespace}/{key}	GET	VersionDictResponse	Get the version strings for a given object type, namespace, and key.
/versions/{objtype}/{namespace}/{key}/list	GET	ListOfStringsResponse	Get the list (without the enclosing dict) of version strings for a given object type, namespace, and key.
/objects/DecisionPoint/{namespace}/{key}/{version}	GET	DecisionPoint	Get an object by objtype, namespace, key, and version
/objects/DecisionTable/{namespace}/{key}/{version}	GET	DecisionTable	Get an object by objtype, namespace, key, and version

…ypes

…shed commits) Squashed commits: [15dd288] add unit tests for Objects API in test_objects.py [b9f2d70] add unit tests for Versions API in test_versions.py [ca2a5b0] rename test files for Keys and Namespaces APIs [4b78a6f] add unit tests for Keys API in test_keys.py [8963982] add unit tests for Namespaces API in test_namespaces.py [7fb49a3] add unit tests for Types API in test_types.py [a34e48a] add unit tests for Decision Point API in test_decision_table.py [7fc227b] refactor test setup for Decision Point API and improve registry handling [d69e29c] add unit tests for Decision Point API endpoints [8770218] rename ListOfStringsType to StringsListType for consistency across response models [7eb02a9] add _404_on_none helper function and corresponding tests

…SON object

…stapi

sei-vsarvepalli

Project moonshot..

…stapi # Conflicts: # requirements.txt

bernhardreiter and others added 19 commits August 19, 2025 11:14

squash changes

0ff5fe0

# Conflicts: # docker/Dockerfile

add uv to manage pyproject.toml

ba7ce14

we don't use dataclasses-json anymore

e8547df

update require ments.txt

d67b357

bump python version to 3.11

7de36b0

bump python to 3.12

a1216f2

add make dev environment target

e111f4f

add mkdocs-exec

c12f28a

swap print() for logger.warning()

1b23c9c

uv --project=./src add "fastapi[standard]"

b277f90

uv --project=./src add "fastapi[all]"

8df22d4

add first pass at registry api

cac5665

add docker ignore

dbb8c2f

add api server to docker config

86fd0ec

refactor

c9d3955

add some basic 404s

2bee844

add some basic 404s

cd8e584

update requirements.txt

e74dcfc

Merge branch 'feature/fastapi' of https://github.com/CERTCC/SSVC into…

442afeb

… feature/fastapi

ahouseholder self-assigned this Aug 20, 2025

ahouseholder added the tech/backend Back-end tools, code, infrastructure label Aug 20, 2025

ahouseholder added this to the 2025-09 milestone Aug 20, 2025

ahouseholder added 3 commits August 20, 2025 12:16

fix python-app.yml for uv

eec60b8

Merge branch 'main' of https://github.com/CERTCC/SSVC into feature/fa…

7fe43d8

…stapi

fix link_checker.yml for uv

1b27670

ahouseholder added 4 commits August 20, 2025 15:15

refactor api and add more routes

85caa25

add __init__.py to ssvc/decision_tables/cisa to fix importer

92b8cb9

refactor

2534633

add lookup by id string

ef4a9b3

ahouseholder added 5 commits August 21, 2025 15:57

improve type defs

dc9c954

validate expected dictionary keys

a031e48

add decision_points/namespace/key/latest/values route

a99e4c7

reorganize type defs

c0d6956

add TypesDictType definition and update descriptions for clarity

4506211

ahouseholder added 3 commits August 21, 2025 16:25

add TypesDictResponse model and update response handling for object t…

1062ba9

…ypes

fix import path for _404_on_none helper in test_helpers.py

72f2c26

ahouseholder changed the title ~~Add fastapi docker container and convert package management to uv~~ Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv Aug 22, 2025

ahouseholder marked this pull request as ready for review August 22, 2025 16:09

ahouseholder requested review from sei-vsarvepalli and cgyarbrough as code owners August 22, 2025 16:09

ahouseholder added 4 commits August 22, 2025 12:54

add documentation for Decision Point and Decision Table objects

6cc7e02

add documentation for Human Impact and update navigation in mkdocs

414bd20

add Dockerfile and docker-compose updates for improved environment setup

c43d1fb

add SSVC Docker Containers documentation and update mkdocs.yml

b400eae

ahouseholder requested a review from j--- as a code owner August 22, 2025 19:36

ahouseholder and others added 8 commits August 22, 2025 15:37

Merge branch 'feature/fastapi' into add-docs-2

9c63e71

add Public Safety Impact decision table, documentation, and related J…

7badc29

…SON object

add code examples and fix filename for utility documentation

f3f05aa

add subgraph structure for inputs and outputs in diagram generation

e704717

add reference docs for SSVC and CVSS collections decision point groups.

12abad3

Add Documentation for DecisionTable objects (#900)

6309262

Merge branch 'main' of https://github.com/CERTCC/SSVC into feature/fa…

d801c08

…stapi

catch pyproject.toml up to main

28d8755

sei-vsarvepalli approved these changes Aug 26, 2025

View reviewed changes

Merge branch 'main' of https://github.com/CERTCC/SSVC into feature/fa…

dfafbe2

…stapi # Conflicts: # requirements.txt

ahouseholder merged commit d114ec9 into main Aug 26, 2025
5 checks passed

ahouseholder deleted the feature/fastapi branch August 26, 2025 20:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv #893

Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv #893

Uh oh!

ahouseholder commented Aug 20, 2025 •

edited

Loading

Uh oh!

ahouseholder commented Aug 20, 2025

Uh oh!

ahouseholder commented Aug 21, 2025 •

edited

Loading

Uh oh!

sei-vsarvepalli left a comment

Uh oh!

Uh oh!

Uh oh!

Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv #893

Add FastAPI for SsvcObjectRegistry, including docker container. Also convert package management to uv #893

Uh oh!

Conversation

ahouseholder commented Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Copilot Summary as of 1062ba9

Uh oh!

ahouseholder commented Aug 20, 2025

Uh oh!

ahouseholder commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sei-vsarvepalli left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ahouseholder commented Aug 20, 2025 •

edited

Loading

Copilot Summary as of `1062ba9`

ahouseholder commented Aug 21, 2025 •

edited

Loading