TMF639 Resource Inventory Management Service¶
A FastAPI-based REST service for managing Resources following the TM Forum OpenAPI TMF-639 specification v5.0.0.
Features¶
CRUD Operations: Full support for Create, Read, Update, and Delete operations on Resources
TMF639 v5.0.0 Compliance: Implements the TM Forum TMF-639 Resource Inventory Management API v5.0.0
SQLAlchemy ORM: Uses SQLAlchemy for database persistence (SQLite by default, configurable for PostgreSQL/MySQL)
FastAPI Framework: Modern, fast web framework with automatic API documentation
Event Subscriptions: Support for registering event listeners (hub endpoints with GET support)
Advanced Filtering: Support for pagination, sorting, and filtering
What’s New in v5.0.0¶
New API Path:
/resourceInventory/v5(instead of/tmf-api/resourceInventoryManagement/v4)New Resource Fields:
validFor: Time period for resource validityresourceOrderItem: Related resource order itemssupportingResource: List of supporting resourcesactivationFeature: Configuration featuresintent: Intent referenceexternalIdentifier: External system identifiersplace: Now an array instead of single object
New Resource Status Values:
installed,not exists,pendingRemoval,plannedEnhanced Hub/Event Subscription: Added GET endpoint to retrieve subscriptions
Advanced Query Parameters:
before,after,sort,filterfor resource listingImproved Related Party Structure: Using
RelatedPartyRefOrPartyRoleRef
Project Structure¶
component-registry-service-tmf639/
├── app/
│ ├── __init__.py # Package initialization
│ ├── main.py # FastAPI application and endpoints
│ ├── database.py # Database configuration
│ ├── models.py # SQLAlchemy database models
│ ├── schemas.py # Pydantic schemas for validation
│ └── crud.py # CRUD operations
├── openapi/ # OpenAPI specification
│ ├── TMF639-Resource_Inventory_Management-v5.0.0.oas.yaml
│ └── TMF639_Resource_Inventory_Management_API_v4.0.0_swagger.json
├── Dockerfile # Container image definition
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore file
└── README.md # This file
Installation¶
Prerequisites¶
Python 3.11 or higher
pip (Python package manager)
Local Setup¶
Create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
Install dependencies:
pip install -r requirements.txt
Run the service:
python -m app.main
Or using uvicorn directly:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8080
The service will start on http://localhost:8080
Docker Setup¶
Build the Docker image:
docker build -t tmf639-resource-inventory:v5.0.0 .
Run the container:
docker run -p 8080:8080 tmf639-resource-inventory:v5.0.0
API Documentation¶
Once the service is running, you can access:
Swagger UI: http://localhost:8080/docs
ReDoc: http://localhost:8080/redoc
OpenAPI JSON: http://localhost:8080/openapi.json
API Endpoints¶
Resource Management (v5.0.0)¶
GET /resourceInventory/v5/resource- List all resources (with filtering, sorting, pagination)POST /resourceInventory/v5/resource- Create a new resourceGET /resourceInventory/v5/resource/{id}- Retrieve a specific resourcePATCH /resourceInventory/v5/resource/{id}- Update a resourceDELETE /resourceInventory/v5/resource/{id}- Delete a resource
Event Subscriptions (v5.0.0)¶
POST /resourceInventory/v5/hub- Create a subscription (hub)GET /resourceInventory/v5/hub/{id}- Retrieve a subscription (hub) ⭐ NEW in v5.0.0DELETE /resourceInventory/v5/hub/{id}- Delete a subscription (hub)
Health Check¶
GET /health- Service health check
Configuration¶
The service can be configured using environment variables:
DATABASE_URL: Database connection string (default:sqlite:///./resource_inventory.db)HOST: Host address to bind (default:0.0.0.0)PORT: Port to listen on (default:8080)
Database Configuration¶
SQLite (default):
export DATABASE_URL="sqlite:///./resource_inventory.db"
PostgreSQL:
export DATABASE_URL="postgresql://user:password@localhost/dbname"
MySQL:
export DATABASE_URL="mysql+pymysql://user:password@localhost/dbname"
Example Usage (v5.0.0)¶
Create a Resource with ID¶
curl -X POST "http://localhost:8080/resourceInventory/v5/resource" \
-H "Content-Type: application/json" \
-d '{
"id": "resource-12345",
"name": "Server-001",
"category": "Physical",
"description": "Production web server",
"resourceStatus": "available",
"administrativeState": "unlocked",
"operationalState": "enable",
"usageState": "idle",
"validFor": {
"startDateTime": "2025-01-01T00:00:00Z",
"endDateTime": "2025-12-31T23:59:59Z"
},
"place": [
{
"id": "datacenter-01",
"name": "Main Data Center",
"role": "installation"
}
],
"externalIdentifier": [
{
"id": "EXT-12345",
"owner": "Legacy System",
"externalIdentifierType": "AssetID"
}
]
}'
Create a Resource without ID (Auto-generated)¶
curl -X POST "http://localhost:8080/resourceInventory/v5/resource" \
-H "Content-Type: application/json" \
-d '{
"name": "Server-002",
"category": "Physical",
"resourceStatus": "planned"
}'
List Resources with Filtering¶
curl -X GET "http://localhost:8080/resourceInventory/v5/resource?limit=10&offset=0&sort=name"
Get a Specific Resource¶
curl -X GET "http://localhost:8080/resourceInventory/v5/resource/resource-12345"
Update a Resource¶
curl -X PATCH "http://localhost:8080/resourceInventory/v5/resource/resource-12345" \
-H "Content-Type: application/json" \
-d '{
"description": "Updated production web server",
"resourceStatus": "reserved",
"activationFeature": [
{
"id": "feature-001",
"name": "Auto-scaling",
"isEnabled": true
}
]
}'
Delete a Resource¶
curl -X DELETE "http://localhost:8080/resourceInventory/v5/resource/resource-12345"
Create Event Subscription (Hub)¶
curl -X POST "http://localhost:8080/resourceInventory/v5/hub" \
-H "Content-Type: application/json" \
-d '{
"callback": "https://myserver.com/listener",
"query": "eventType=ResourceCreateEvent"
}'
Get Event Subscription (Hub) ⭐ NEW¶
curl -X GET "http://localhost:8080/resourceInventory/v5/hub/{hub-id}"
Development¶
Running Tests¶
pytest
Code Formatting¶
black app/
Type Checking¶
mypy app/
TMF639 v5.0.0 Compliance¶
This implementation follows the TM Forum TMF-639 Resource Inventory Management API specification v5.0.0. It includes:
Resource entity with full attribute support including v5.0.0 new fields
Characteristics, relationships, and attachments
Related parties using new
RelatedPartyRefOrPartyRoleRefstructurePlaces as array (changed from v4.0.0)
Administrative, operational, resource (extended), and usage state enumerations
Event subscription mechanisms with GET support
External identifiers for cross-system integration
Supporting resources and activation features
Intent reference support
Proper HTTP status codes and error responses
Advanced query parameters (filter, sort, before, after)
Migration from v4.0.0 to v5.0.0¶
If you are migrating from v4.0.0:
Update API paths: Change
/tmf-api/resourceInventoryManagement/v4to/resourceInventory/v5Update place structure:
placeis now an array instead of a single objectAdd new optional fields:
validFor,resourceOrderItem,supportingResource,activationFeature,intent,externalIdentifierUpdate status values: New values available for
resourceStatusHub GET support: You can now retrieve hub subscriptions by ID
License¶
This project is part of the ODA Canvas Reference Implementation.
Contributing¶
Please refer to the main ODA Canvas contribution guidelines in the repository root.
Buildautomation and Versioning¶
The build and release process for docker images is described here: docs/developer/work-with-dockerimages.md