ಹುಡುಕಾಟ ಮತ್ತು ಫಿಲ್ಟರಿಂಗ್ ಸಹಿತ service catalog REST API ನಿರ್ಮಿಸಿ

ಪರಿಚಯ

ನೀವು ಸರ್ವಿಸ್ ಕ್ಯಾಟಲಾಗ್ ಅನ್ನು ಪ್ರಕಟಿಸಿದರೂ ಅದನ್ನು ಪ್ರೋಗ್ರಾಮ್ ಮೂಲಕ ಪ್ರಶ್ನಿಸುವ ಮಾರ್ಗವನ್ನು ಗ್ರಾಹಕರಿಗೆ ನೀಡದಿದ್ದರೆ, ತಂಡಗಳು Git ರೆಪೊದಲ್ಲಿರುವ ಕಚ್ಚಾ YAML ಓದುವುದು, Slack ಸಂದೇಶಗಳ ಸ್ಕ್ರೀನ್‌ಶಾಟ್ ತೆಗೆಯುವುದು, ಅಥವಾ ಟಿಕೆಟ್‌ನಲ್ಲಿ ಪ್ಲಾಟ್‌ಫಾರ್ಮ್ ತಂಡವನ್ನು "ನಾವು ಯಾವ ವೆಕ್ಟರ್ ಡೇಟಾಬೇಸ್‌ಗಳನ್ನು ನೀಡುತ್ತೇವೆ?" ಎಂದು ಕೇಳುವುದಕ್ಕೆ ಮರಳುತ್ತವೆ. ಕ್ಯಾಟಲಾಗ್ ಡೇಟಾ ಇದೆ, ಆದರೆ ಅದು ಕಂಡುಹಿಡಿಯಲು ಸಾಧ್ಯವಿಲ್ಲ—ಮಾನವನ ಮಧ್ಯಸ್ಥಿಕೆ ಇಲ್ಲದೆ "team-beta ಒಡೆತನದ, GPU-ಆಧಾರಿತ ಪ್ರತಿಯೊಂದು ಮಾಡೆಲ್-ಸರ್ವಿಂಗ್ ಎಂಟ್ರಿಯನ್ನು, ಹೊಸ ಆವೃತ್ತಿ ಮೊದಲಿಗೆ ಬರುವಂತೆ ತೋರಿಸು" ಎಂಬುದಕ್ಕೆ ಇಂಜಿನಿಯರ್‌ಗಳು ಉತ್ತರಿಸಲಾರರು. API ಪದರವು ಕ್ಯಾಟಲಾಗ್ ಅನ್ನು HTTP ಮೂಲಕ ರಚನಾತ್ಮಕ ಹುಡುಕಾಟ, ವರ್ಗ ಫಿಲ್ಟರಿಂಗ್, ಪೇಜಿನೇಷನ್ ಮತ್ತು ಸ್ಪಷ್ಟ ಪ್ರತಿಕ್ರಿಯೆ ಆವೃತ್ತಿಯೊಂದಿಗೆ ಬಹಿರಂಗಪಡಿಸಿ ಈ ಅಂತರವನ್ನು ಮುಚ್ಚುತ್ತದೆ, ಇದರಿಂದ ಡೆವಲಪರ್ ಪೋರ್ಟಲ್‌ಗಳು, CLIಗಳು ಮತ್ತು CI ಪೈಪ್‌ಲೈನ್‌ಗಳು ಎಲ್ಲವೂ ಒಂದೇ ಒಪ್ಪಂದವನ್ನು ಬಳಸಬಹುದು. ಈ ಪಾಠದ ಕೊನೆಯ ವೇಳೆಗೆ, ಗ್ರಾಹಕರ ಇನ್‌ಪುಟ್ ಅನ್ನು ಮೌಲ್ಯೀಕರಿಸುವ ಪ್ರಶ್ನೆ ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆ ಸ್ಕೀಮಾಗಳನ್ನು ವ್ಯಾಖ್ಯಾನಿಸಲು, ಕ್ಯಾಟಲಾಗ್ ಸ್ಟೋರ್ ವಿರುದ್ಧ ಚಲಿಸುವ ಪೂರ್ಣ-ಪಠ್ಯ ಹುಡುಕಾಟ ಮತ್ತು ವರ್ಗ ಫಿಲ್ಟರ್ ಅನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸಲು, ಮತ್ತು ಅಸ್ತಿತ್ವದಲ್ಲಿರುವ ಕ್ಲೈಂಟ್‌ಗಳನ್ನು ಮುರಿಯದೆ ಪೇಲೋಡ್ ಆಕಾರವನ್ನು ವಿಕಸನಗೊಳಿಸಲು ಅನುವು ಮಾಡಿಕೊಡುವ ಆವೃತ್ತಿಯುಕ್ತ ಎನ್‌ವೆಲಪ್‌ನಲ್ಲಿ ಫಲಿತಾಂಶಗಳನ್ನು ಸುತ್ತಲು ನೀವು ಸಮರ್ಥರಾಗುವಿರಿ.

ಪ್ರಮುಖ ಪರಿಭಾಷೆ

• Catalog API: ಸರ್ವಿಸ್ ಕ್ಯಾಟಲಾಗ್ ಮೇಲಿನ ಓದುವ ಕಾರ್ಯಾಚರಣೆಗಳನ್ನು—ಪಟ್ಟಿ ಮಾಡುವುದು, ಹುಡುಕುವುದು, ಫಿಲ್ಟರ್ ಮಾಡುವುದು ಮತ್ತು ಪ್ರತ್ಯೇಕ ಎಂಟ್ರಿಗಳನ್ನು ಪಡೆಯುವುದು—ಪ್ಲಾಟ್‌ಫಾರ್ಮ್ ಗ್ರಾಹಕರಿಗೆ ಬಹಿರಂಗಪಡಿಸುವ HTTP ಇಂಟರ್‌ಫೇಸ್.
• Query Parameter Model: URL ಕ್ವೆರಿ ಸ್ಟ್ರಿಂಗ್ ಆರ್ಗ್ಯುಮೆಂಟ್‌ಗಳನ್ನು ಟೈಪ್ ಮಾಡಿದ ಫೀಲ್ಡ್‌ಗಳಿಗೆ ಬಂಧಿಸುವ, ಯಾವುದೇ ಸ್ಟೋರ್ ಪ್ರವೇಶಕ್ಕೂ ಮೊದಲು ತಪ್ಪಾದ ವಿನಂತಿಗಳನ್ನು ತಿರಸ್ಕರಿಸುವ ಮೌಲ್ಯೀಕರಿಸಿದ ಸ್ಕೀಮಾ (CatalogQuery).
• Response Envelope: ಫಲಿತಾಂಶ ಐಟಂಗಳ ಜೊತೆಗೆ ಒಟ್ಟು ಎಣಿಕೆ, ಪೇಜಿನೇಷನ್ ಕರ್ಸರ್ ಮತ್ತು API ಆವೃತ್ತಿಯಂತಹ ಮೆಟಾಡೇಟಾವನ್ನು ಹೊತ್ತೊಯ್ಯುವ ಹೊದಿಕೆ ವಸ್ತು (CatalogListResponse).
• API Versioning: ಗ್ರಾಹಕರು ಮೌನವಾಗಿ ಮುರಿಯುವ ಬದಲು ಸ್ಕೀಮಾ ಬದಲಾವಣೆಗಳನ್ನು ಪತ್ತೆಹಚ್ಚಿ ಹೊಂದಿಕೊಳ್ಳುವಂತೆ ಪ್ರತಿ ಪ್ರತಿಕ್ರಿಯೆಯಲ್ಲಿ ಸ್ಪಷ್ಟ api_version ಫೀಲ್ಡ್ ಅನ್ನು ಅಳವಡಿಸುವುದು.
• Category Filter: ServiceCategory ಗೆ ಹೊಂದಿಕೆಯಾಗುವ ಎಂಟ್ರಿಗಳಿಗೆ ಫಲಿತಾಂಶಗಳನ್ನು ಸಂಕುಚಿತಗೊಳಿಸುವ ಸರ್ವರ್-ಬದಿಯ ಷರತ್ತು, ಎಣಿಕೆಗಳು ನಿಖರವಾಗಿ ಉಳಿಯುವಂತೆ ಪೇಜಿನೇಷನ್‌ಗೂ ಮೊದಲು ಅನ್ವಯಿಸಲಾಗುತ್ತದೆ.

ಪರಿಕಲ್ಪನೆಗಳು

ಈಗ ನಮ್ಮಲ್ಲಿ ಬಹಿರಂಗಪಡಿಸಲು ಕ್ಯಾಟಲಾಗ್ ಡೇಟಾ ಮಾಡೆಲ್ ಇರುವುದರಿಂದ, API ಪದರವು ಪ್ಲಾಟ್‌ಫಾರ್ಮ್ ಗ್ರಾಹಕರು ಮತ್ತು ಆಧಾರವಾಗಿರುವ ಎಂಟ್ರಿ ಸ್ಟೋರ್ ನಡುವೆ ಕುಳಿತು, ಸಡಿಲವಾಗಿ ಟೈಪ್ ಮಾಡಿದ HTTP ಕ್ವೆರಿ ಸ್ಟ್ರಿಂಗ್‌ಗಳನ್ನು ಮೌಲ್ಯೀಕರಿಸಿದ, ಫಿಲ್ಟರ್ ಮಾಡಿದ, ಆವೃತ್ತಿಯುಕ್ತ ಪ್ರತಿಕ್ರಿಯೆಗಳಾಗಿ ಭಾಷಾಂತರಿಸುತ್ತದೆ. ಒಂದು ವಿನಂತಿ ನಾಲ್ಕು ಹಂತಗಳ ಮೂಲಕ ಹರಿಯುತ್ತದೆ: ಇನ್‌ಪುಟ್ ಬೈಂಡಿಂಗ್, ಫಿಲ್ಟರಿಂಗ್, ಪೇಜಿನೇಷನ್ ಮತ್ತು ಎನ್‌ವೆಲಪ್ ನಿರ್ಮಾಣ. ಪ್ರತಿ ಹಂತಕ್ಕೂ ಒಂದೇ ಜವಾಬ್ದಾರಿ ಇದೆ, ಮತ್ತು ಅವುಗಳನ್ನು ಪ್ರತ್ಯೇಕವಾಗಿ ಇಡುವುದೇ ಹುಡುಕಾಟ ಎಂಡ್‌ಪಾಯಿಂಟ್ ಅನ್ನು ಪರೀಕ್ಷಿಸಬಹುದಾದ ಮತ್ತು ಪ್ರತಿಕ್ರಿಯೆ ಆಕಾರವನ್ನು ವಿಕಸನಗೊಳಿಸಬಹುದಾದಂತೆ ಮಾಡುತ್ತದೆ.

ಇನ್‌ಪುಟ್ ಬೈಂಡಿಂಗ್ ಹಂತವು ?q=qdrant&category=vector-db&limit=20&offset=0 ಅನ್ನು CatalogQuery ಇನ್‌ಸ್ಟೆನ್ಸ್‌ಗೆ ಮ್ಯಾಪ್ ಮಾಡುತ್ತದೆ. ಟೈಪ್ ಮಾಡಿದ ಮಾಡೆಲ್ ಮೂಲಕ ಬೈಂಡಿಂಗ್ ಮಾಡುವುದರಿಂದ ಅಮಾನ್ಯ limit (ಋಣಾತ್ಮಕ, ಅಥವಾ ಮಿತಿಗಿಂತ ಹೆಚ್ಚು) ಸ್ವಯಂಚಾಲಿತವಾಗಿ 422 ನೊಂದಿಗೆ ತಿರಸ್ಕೃತವಾಗುತ್ತದೆ—ಎಂಡ್‌ಪಾಯಿಂಟ್ ದೇಹವು ಕೆಟ್ಟ ಇನ್‌ಪುಟ್ ವಿರುದ್ಧ ಎಂದಿಗೂ ಚಲಿಸುವುದಿಲ್ಲ. ಫಿಲ್ಟರಿಂಗ್ ಹಂತವು ಎರಡು ಸ್ವತಂತ್ರ ಷರತ್ತುಗಳನ್ನು ಅನ್ವಯಿಸುತ್ತದೆ: q ಪದಕ್ಕಾಗಿ ಎಂಟ್ರಿಯ name ಮತ್ತು description ವಿರುದ್ಧ ಕೇಸ್-ಅಸಂವೇದಿ ಸಬ್‌ಸ್ಟ್ರಿಂಗ್ ಹೊಂದಾಣಿಕೆ, ಮತ್ತು category ಗಾಗಿ ನಿಖರ service_type ಹೊಂದಾಣಿಕೆ. ಎರಡೂ ಐಚ್ಛಿಕ; ಯಾವುದನ್ನಾದರೂ ಬಿಟ್ಟುಬಿಟ್ಟರೆ ದೋಷ ಬರುವ ಬದಲು ಫಲಿತಾಂಶ ಸೆಟ್ ವಿಸ್ತಾರವಾಗುತ್ತದೆ.

ಕೊನೆಯ ಎರಡು ಹಂತಗಳ ನಡುವೆ ಕ್ರಮವು ಮುಖ್ಯ. total ಎಲ್ಲಾ ಎಂಟ್ರಿಗಳ ಎಣಿಕೆಯನ್ನಲ್ಲ, ಹೊಂದಿಕೆಯಾಗುವ ಎಂಟ್ರಿಗಳ ಎಣಿಕೆಯನ್ನು ಪ್ರತಿಬಿಂಬಿಸುವಂತೆ ಫಿಲ್ಟರಿಂಗ್ ಪೇಜಿನೇಷನ್‌ಗೂ ಮೊದಲು ಪೂರ್ಣಗೊಳ್ಳಬೇಕು. ನೀವು ಮೊದಲು ಪೇಜಿನೇಟ್ ಮಾಡಿ ನಂತರ ಪುಟವನ್ನು ಫಿಲ್ಟರ್ ಮಾಡಿದರೆ, ಹುಡುಕಾಟದ ಎರಡನೇ ಪುಟವು ಮೊದಲ ಪುಟದಲ್ಲಿ ಬಿದ್ದ ಹೊಂದಾಣಿಕೆಗಳನ್ನು ಮೌನವಾಗಿ ಕೈಬಿಡುತ್ತದೆ, ಮತ್ತು ಒಟ್ಟು ಎಣಿಕೆ ಅರ್ಥಹೀನವಾಗುತ್ತದೆ. ಇಡೀ ಸೆಟ್ ಮೇಲೆ apply_filters ಅನ್ನು ಚಲಾಯಿಸಿ, ಫಿಲ್ಟರ್ ಮಾಡಿದ ಉದ್ದದಿಂದ total ಅನ್ನು ಲೆಕ್ಕಹಾಕಿ, ಆ ನಂತರವೇ paginate ನೊಂದಿಗೆ ಕತ್ತರಿಸುವುದು ಪೇಜಿನೇಷನ್ ಮೆಟಾಡೇಟಾವನ್ನು ಪ್ರಾಮಾಣಿಕವಾಗಿ ಇಡುತ್ತದೆ.

ಪ್ರತಿಕ್ರಿಯೆ ಎನ್‌ವೆಲಪ್ ಆವೃತ್ತೀಕರಣವು ವಾಸಿಸುವ ಸ್ಥಳ. ಬರಿಯ JSON ಅರೇ ಹಿಂತಿರುಗಿಸುವ ಬದಲು, list_services api_version, items, total, limit ಮತ್ತು offset ಅನ್ನು ಹೊತ್ತ CatalogListResponse ಅನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ. ಗ್ರಾಹಕರು ಪೇಲೋಡ್ ಅನ್ನು ಅರ್ಥಮಾಡಿಕೊಳ್ಳುತ್ತಾರೆಯೇ ಎಂದು ನಿರ್ಧರಿಸಲು api_version ಅನ್ನು ಓದುತ್ತಾರೆ. ನೀವು ನಂತರ ಒಂದು ಫೀಲ್ಡ್ ಸೇರಿಸಿದಾಗ—ಉದಾಹರಣೆಗೆ deprecation_notice—api_version "v1" ಗೆ ಪಿನ್ ಮಾಡಿದ ಹಳೆಯ ಕ್ಲೈಂಟ್‌ಗಳು ಕೆಲಸ ಮಾಡುತ್ತಲೇ ಇರುತ್ತವೆ ಏಕೆಂದರೆ ಒಂದು ಆವೃತ್ತಿಯೊಳಗಿನ ಸೇರ್ಪಡೆ ಬದಲಾವಣೆಗಳು ಸುರಕ್ಷಿತ, ಮತ್ತು ಮುರಿಯುವ ಬದಲಾವಣೆಯು ಆವೃತ್ತಿಯನ್ನು ಹೆಚ್ಚಿಸುತ್ತದೆ ಇದರಿಂದ ಕ್ಲೈಂಟ್‌ಗಳು ಅದರ ಮೇಲೆ ಕವಲೊಡೆಯಬಹುದು. ಇದು ನೀವು ಕ್ಯಾಟಲಾಗ್ ಎಂಟ್ರಿಗಳಿಗೇ ಅನ್ವಯಿಸುವ ಅದೇ ಶಿಸ್ತು, ಟ್ರಾನ್ಸ್‌ಪೋರ್ಟ್ ಪದರಕ್ಕೆ ವಿಸ್ತರಿಸಲಾಗಿದೆ.

ಕೋಡ್ ವಾಕ್‌ಥ್ರೂ

ನಾಲ್ಕು-ಹಂತದ ವಿನಂತಿ ಹರಿವನ್ನು ಪರಿಶೀಲಿಸಿದ ನಂತರ, ಕೆಳಗಿನ ಅನುಷ್ಠಾನವು ಅದನ್ನು ಎರಡು ಭಾಗಗಳಾಗಿ ಎನ್‌ಕೋಡ್ ಮಾಡುತ್ತದೆ: HTTP ಒಪ್ಪಂದವನ್ನು ಬಂಧಿಸಿ ಮೌಲ್ಯೀಕರಿಸುವ ವಿನಂತಿ/ಪ್ರತಿಕ್ರಿಯೆ ಸ್ಕೀಮಾಗಳು, ಮತ್ತು ಹುಡುಕಾಟ, ಫಿಲ್ಟರಿಂಗ್ ಮತ್ತು ಪೇಜಿನೇಷನ್ ಅನ್ನು ಎರಡು ಎಂಡ್‌ಪಾಯಿಂಟ್‌ಗಳಿಗೆ ಜೋಡಿಸುವ FastAPI ರೂಟರ್. ಮೊದಲ ಬ್ಲಾಕ್ ServiceCategory, CatalogQuery ಇನ್‌ಪುಟ್ ಮಾಡೆಲ್, ಪ್ರತಿ-ಐಟಂ CatalogItemResponse, ಮತ್ತು ಆವೃತ್ತಿಯುಕ್ತ CatalogListResponse ಎನ್‌ವೆಲಪ್ ಅನ್ನು ವ್ಯಾಖ್ಯಾನಿಸುತ್ತದೆ—ತಪ್ಪಾದ ವಿನಂತಿಗಳು ಹ್ಯಾಂಡ್ಲರ್‌ನ ಆಳದಲ್ಲಿ ಅಲ್ಲ, ಬೈಂಡಿಂಗ್ ಸಮಯದಲ್ಲೇ ವಿಫಲವಾಗುವಂತೆ ಪ್ರತಿ ಫೀಲ್ಡ್ ನಿರ್ಬಂಧಿಸಲಾಗಿದೆ.

Code snippetpython
1from pydantic import BaseModel, Field
2from enum import Enum
3from typing import Optional
4
5CATALOG_API_VERSION = "v1"
6
7class ServiceCategory(str, Enum):
8    MODEL_SERVING = "model-serving"
9    TRAINING_JOB = "training-job"
10    VECTOR_DB = "vector-db"
11    FEATURE_STORE = "feature-store"
12    MONITORING = "monitoring"
13
14class CatalogQuery(BaseModel):
15    q: Optional[str] = Field(default=None, max_length=128)
16    category: Optional[ServiceCategory] = None
17    limit: int = Field(default=25, ge=1, le=100)
18    offset: int = Field(default=0, ge=0)
19
20class CatalogItemResponse(BaseModel):
21    service_id: str
22    name: str
23    service_type: ServiceCategory
24    version: str
25    owner_team: str
26    description: str
27    deprecated: bool
28
29class CatalogListResponse(BaseModel):
30    api_version: str = CATALOG_API_VERSION
31    total: int
32    limit: int
33    offset: int
34    items: list[CatalogItemResponse]

• ಸಾಲುಗಳು 6-12: ServiceCategory ಕ್ಯಾಟಲಾಗ್‌ನ ಸರ್ವಿಸ್-ಟೈಪ್ ವರ್ಗೀಕರಣದ ಅದೇ kebab-case ಮೌಲ್ಯಗಳನ್ನು ಮರುಬಳಕೆ ಮಾಡುತ್ತದೆ, ಆದ್ದರಿಂದ ನಿಜವಾದ ವರ್ಗವಲ್ಲದ category ಕ್ವೆರಿ ಪ್ಯಾರಾಮೀಟರ್ ಬೈಂಡಿಂಗ್‌ನಲ್ಲೇ ತಿರಸ್ಕೃತವಾಗುತ್ತದೆ—ಹ್ಯಾಂಡ್ಲರ್ ಒಳಗೆ ಕೈಯಾರೆ ಮೌಲ್ಯೀಕರಿಸುವ ಅಗತ್ಯವಿಲ್ಲ.
• ಸಾಲುಗಳು 14-18: CatalogQuery limit ಅನ್ನು [1, 100] ಗೆ ಮತ್ತು offset ಅನ್ನು ≥ 0 ಗೆ ಮಿತಿಗೊಳಿಸುತ್ತದೆ. limit=5000 ಕೇಳುವ ಕ್ಲೈಂಟ್‌ಗೆ 422 ಸಿಗುತ್ತದೆ, ಇದು ಸ್ಟೋರ್ ಅನ್ನು ಮಿತಿಯಿಲ್ಲದ ಸ್ಕ್ಯಾನ್‌ಗಳಿಂದ ರಕ್ಷಿಸುತ್ತದೆ; ಎರಡೂ ಹುಡುಕಾಟ ಫೀಲ್ಡ್‌ಗಳು ಡೀಫಾಲ್ಟ್ ಆಗಿ None ಆಗಿರುವುದರಿಂದ ಆರ್ಗ್ಯುಮೆಂಟ್-ರಹಿತ ವಿನಂತಿಯು ಎಲ್ಲದರ ಮೊದಲ ಪುಟವನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ.
• ಸಾಲುಗಳು 28-33: CatalogListResponse api_version ಅನ್ನು ಡೀಫಾಲ್ಟ್ ಆಗಿ CATALOG_API_VERSION ಗೆ ಹೊಂದಿಸುತ್ತದೆ, ಆದ್ದರಿಂದ ಪ್ರತಿ ಪ್ರತಿಕ್ರಿಯೆಯೂ ಸ್ವಯಂ-ವಿವರಣಾತ್ಮಕ; total items ಪಕ್ಕದಲ್ಲಿ ಇರುವುದರಿಂದ ಗ್ರಾಹಕರು ಎರಡನೇ ಕರೆ ಇಲ್ಲದೆ ಎಷ್ಟು ಪುಟಗಳು ಉಳಿದಿವೆ ಎಂದು ಲೆಕ್ಕಹಾಕಬಹುದು.

ಎರಡನೇ ಬ್ಲಾಕ್ ಫಿಲ್ಟರಿಂಗ್ ಮತ್ತು ಪೇಜಿನೇಷನ್ ಶುದ್ಧ ಫಂಕ್ಷನ್‌ಗಳನ್ನು ಹಾಗೂ ಎರಡು ಎಂಡ್‌ಪಾಯಿಂಟ್‌ಗಳನ್ನು ಕಾರ್ಯಗತಗೊಳಿಸುತ್ತದೆ. apply_filters ಪೂರ್ಣ ಎಂಟ್ರಿ ಸೆಟ್ ಮೇಲೆ ಎರಡೂ ಷರತ್ತುಗಳನ್ನು ಚಲಾಯಿಸುತ್ತದೆ; paginate ಫಿಲ್ಟರ್ ಮಾಡಿದ ಪಟ್ಟಿಯನ್ನು ಕತ್ತರಿಸುತ್ತದೆ; list_services ಅವುಗಳನ್ನು ಸಂಯೋಜಿಸಿ ಎನ್‌ವೆಲಪ್ ನಿರ್ಮಿಸುತ್ತದೆ; get_service ಏಕ-ಎಂಟ್ರಿ ಲುಕ್‌ಅಪ್ ಅನ್ನು ನಿರ್ವಹಿಸಿ service_id ಅಪರಿಚಿತವಾದಾಗ 404 ಅನ್ನು raise ಮಾಡುತ್ತದೆ.

Code snippetpython
1from fastapi import APIRouter, Depends, HTTPException
2
3router = APIRouter(prefix="/catalog", tags=["catalog"])
4
5def apply_filters(entries: list, query: CatalogQuery) -> list:
6    results = entries
7    if query.category is not None:
8        results = [e for e in results if e.service_type == query.category]
9    if query.q:
10        term = query.q.lower()
11        results = [
12            e for e in results
13            if term in e.name.lower() or term in e.description.lower()
14        ]
15    return results
16
17def paginate(entries: list, limit: int, offset: int) -> list:
18    return entries[offset : offset + limit]
19
20@router.get("", response_model=CatalogListResponse)
21def list_services(query: CatalogQuery = Depends(), store=Depends(get_catalog_store)):
22    matched = apply_filters(store.all_entries(), query)
23    page = paginate(matched, query.limit, query.offset)
24    return CatalogListResponse(
25        total=len(matched),
26        limit=query.limit,
27        offset=query.offset,
28        items=[CatalogItemResponse(**e.model_dump()) for e in page],
29    )
30
31@router.get("/{service_id}", response_model=CatalogItemResponse)
32def get_service(service_id: str, store=Depends(get_catalog_store)):
33    entry = store.get(service_id)
34    if entry is None:
35        raise HTTPException(status_code=404, detail=f"unknown service_id: {service_id}")
36    return CatalogItemResponse(**entry.model_dump())

• ಸಾಲುಗಳು 5-15: apply_filters ಮೊದಲು ವರ್ಗ ಷರತ್ತನ್ನು (ಅಗ್ಗದ ನಿಖರ ಹೊಂದಾಣಿಕೆ) ನಂತರ ಸಬ್‌ಸ್ಟ್ರಿಂಗ್ ಹುಡುಕಾಟವನ್ನು ಅನ್ವಯಿಸುತ್ತದೆ, ಎರಡೂ is not None / truthiness ನಿಂದ ಕಾವಲು ಮಾಡಲ್ಪಟ್ಟಿವೆ, ಆದ್ದರಿಂದ ಬಿಟ್ಟುಬಿಟ್ಟ ಪ್ಯಾರಾಮೀಟರ್ ಏನನ್ನೂ ಫಿಲ್ಟರ್ ಮಾಡದೆ ಫಲಿತಾಂಶಗಳನ್ನು ವಿಸ್ತರಿಸುವ no-op ಆಗುತ್ತದೆ.
• ಸಾಲುಗಳು 22-30: list_services ಇಡೀ ಸೆಟ್ ಮೇಲೆ matched ಅನ್ನು ಲೆಕ್ಕಹಾಕಿ, ಕತ್ತರಿಸುವ ಮೊದಲು len(matched) ನಿಂದ total ಅನ್ನು ಪಡೆದು, ನಂತರ ಪೇಜಿನೇಟ್ ಮಾಡುತ್ತದೆ—ಎನ್‌ವೆಲಪ್‌ನ total ಕಚ್ಚಾ ಕ್ಯಾಟಲಾಗ್ ಗಾತ್ರವನ್ನಲ್ಲ, ಹೊಂದಾಣಿಕೆಗಳನ್ನು ಎಣಿಸುತ್ತದೆ ಎಂಬುದನ್ನು ಖಾತರಿಪಡಿಸುತ್ತದೆ.
• ಸಾಲುಗಳು 33-38: get_service ಏಕ ಎಂಟ್ರಿಯನ್ನು ಹಿಂತಿರುಗಿಸುತ್ತದೆ ಅಥವಾ 404 ನೊಂದಿಗೆ HTTPException ಅನ್ನು raise ಮಾಡುತ್ತದೆ; None ಹಿಂತಿರುಗಿಸಿದರೆ FastAPI ಶೂನ್ಯ ದೇಹವನ್ನು ಸೀರಿಯಲೈಸ್ ಮಾಡುತ್ತದೆ, ಆದ್ದರಿಂದ ಸ್ಪಷ್ಟ raise ಮಾತ್ರವೇ ಗ್ರಾಹಕರಿಗೆ ಕ್ರಮಕೈಗೊಳ್ಳಬಹುದಾದ ದೋಷವನ್ನು ನೀಡುತ್ತದೆ.

GET /catalog?category=vector-db&q=qdrant&limit=5 ಅನ್ನು ಕಳುಹಿಸಿ ಪರಿಶೀಲಿಸಿ—ಪ್ರತಿಕ್ರಿಯೆಯು api_version: "v1", ಹೆಸರು ಅಥವಾ ವಿವರಣೆಯಲ್ಲಿ "qdrant" ಇರುವ ಹೊಂದಿಕೆಯಾಗುವ vector-db ಎಂಟ್ರಿಗಳ ಸಂಖ್ಯೆಗೆ ಸಮಾನವಾದ total, ಮತ್ತು ಗರಿಷ್ಠ ಐದು items ಅನ್ನು ಹೊತ್ತಿರಬೇಕು; ನಂತರ GET /catalog/does-not-exist unknown service_id ವಿವರದೊಂದಿಗೆ 404 ಅನ್ನು ಹಿಂತಿರುಗಿಸಬೇಕು.

ಶಿಸ್ತು ಅನ್ವಯ

ಮಾಡಬೇಕಾದವು ಮತ್ತು ಮಾಡಬಾರದವು

ಮೇಲೆ ಕ್ವೆರಿ ಸ್ಕೀಮಾ, ಫಿಲ್ಟರ್-ನಂತರ-ಪೇಜಿನೇಟ್ ಪೈಪ್‌ಲೈನ್ ಮತ್ತು ಆವೃತ್ತಿಯುಕ್ತ ಎನ್‌ವೆಲಪ್ ಅನ್ನು ಪರಿಶೀಲಿಸಿದ ನಂತರ, ಕೆಳಗಿನ ಆದೇಶಗಳು API-ಒಪ್ಪಂದ ಮತ್ತು ಹುಡುಕಾಟ-ಸರಿಯಾದತೆಯ ಮಾದರಿಗಳನ್ನು ನಿಮ್ಮ ಸ್ವಂತ ಕ್ಯಾಟಲಾಗ್ ಎಂಡ್‌ಪಾಯಿಂಟ್‌ಗಳನ್ನು ನಿರ್ಮಿಸುವಾಗ ನೇರವಾಗಿ ಅನ್ವಯಿಸಬಹುದಾದ ನಿಯಮಗಳಾಗಿ ಬಟ್ಟಿ ಇಳಿಸುತ್ತವೆ.

ಮಾಡಬೇಕಾದವು

1. ಕ್ವೆರಿ ಸ್ಟ್ರಿಂಗ್‌ಗಳನ್ನು Depends() ಜೊತೆಗೆ CatalogQuery ಮಾಡೆಲ್ ಮೂಲಕ ಬಂಧಿಸಿ — Field ನಿರ್ಬಂಧಗಳು (limit [1, 100] ನಲ್ಲಿ, offset ≥ 0, category ServiceCategory ಆಗಿ) list_services ಚಲಿಸುವ ಮೊದಲು ತಪ್ಪಾದ ವಿನಂತಿಗಳನ್ನು 422 ನೊಂದಿಗೆ ತಿರಸ್ಕರಿಸುತ್ತವೆ, ಆದ್ದರಿಂದ ಯಾವುದೇ ಹ್ಯಾಂಡ್ಲರ್ ಕೋಡ್ ಮಿತಿಯಿಲ್ಲದ limit ಅಥವಾ ಅಪರಿಚಿತ ವರ್ಗ ಸ್ಟ್ರಿಂಗ್ ವಿರುದ್ಧ ಎಂದಿಗೂ ಕಾರ್ಯಗತವಾಗುವುದಿಲ್ಲ.
2. apply_filters ಅನ್ನು ಪೂರ್ಣ ಎಂಟ್ರಿ ಸೆಟ್ ಮೇಲೆ ಚಲಾಯಿಸಿ ಮತ್ತು paginate ಕರೆಯುವ ಮೊದಲು len(matched) ನಿಂದ total ಅನ್ನು ಪಡೆಯಿರಿ — ಫಿಲ್ಟರ್ ಮಾಡಿದ-ಆದರೆ-ಕತ್ತರಿಸದ ಪಟ್ಟಿಯ ಮೇಲೆ ಎಣಿಕೆಯನ್ನು ಲೆಕ್ಕಹಾಕುವುದು CatalogListResponse.total ಫೀಲ್ಡ್ ಅನ್ನು ಪ್ರಾಮಾಣಿಕವಾಗಿ ಇಡುತ್ತದೆ, ಆದ್ದರಿಂದ ಗ್ರಾಹಕರು ಹೊಂದಾಣಿಕೆಗಳನ್ನು ಮೌನವಾಗಿ ಕಳೆದುಕೊಳ್ಳದೆ ಹುಡುಕಾಟ ಫಲಿತಾಂಶಗಳ ಮೂಲಕ ಪುಟ ತಿರುಗಿಸಬಹುದು.
3. ಪ್ರತಿ ಪ್ರತಿಕ್ರಿಯೆಗೂ CATALOG_API_VERSION ನಿಂದ api_version ಅನ್ನು ಮುದ್ರಿಸಿ — ಸ್ವಯಂ-ವಿವರಣಾತ್ಮಕ ಎನ್‌ವೆಲಪ್ ಪೋರ್ಟಲ್‌ಗಳು ಮತ್ತು CI ಕ್ಲೈಂಟ್‌ಗಳಿಗೆ ಆವೃತ್ತಿಯ ಮೇಲೆ ಕವಲೊಡೆಯಲು ಅನುವು ಮಾಡಿಕೊಡುತ್ತದೆ ಮತ್ತು ಮುರಿಯುವ ಪೇಲೋಡ್ ಬದಲಾವಣೆಗಳಿಗೆ ಆವೃತ್ತಿ ಹೆಚ್ಚಳವನ್ನು ಕಾಯ್ದಿರಿಸಿಕೊಂಡು "v1" ಒಳಗೆ ಸೇರ್ಪಡೆಯಾಗಿ ಫೀಲ್ಡ್‌ಗಳನ್ನು ಸೇರಿಸಲು ನಿಮಗೆ ಅನುವು ಮಾಡಿಕೊಡುತ್ತದೆ.

ಮಾಡಬಾರದವು

1. ಫಿಲ್ಟರ್ ಮಾಡುವ ಮೊದಲು ಪೇಜಿನೇಟ್ ಮಾಡಬೇಡಿ — ಮೊದಲು store.all_entries() ಅನ್ನು ಕತ್ತರಿಸಿ ನಂತರ ಪುಟದ ಮೇಲೆ apply_filters ಚಲಾಯಿಸುವುದು total ಅನ್ನು ಅರ್ಥಹೀನವಾಗಿಸುತ್ತದೆ ಮತ್ತು ಪ್ರಸ್ತುತ ವಿಂಡೋದ ಹೊರಗೆ ಬೀಳುವ ಹೊಂದಾಣಿಕೆಗಳನ್ನು ಕೈಬಿಡುತ್ತದೆ; ಪೈಪ್‌ಲೈನ್ ಕ್ರಮವೇ (apply_filters → paginate) ಸರಿಯಾದ ಎಣಿಕೆಗಳನ್ನು ಮತ್ತು ಸಂಪೂರ್ಣ ಫಲಿತಾಂಶ ಸೆಟ್‌ಗಳನ್ನು ಖಾತರಿಪಡಿಸುತ್ತದೆ.
2. list_services ನಿಂದ ಬರಿಯ ಪಟ್ಟಿಯನ್ನು ಹಿಂತಿರುಗಿಸಬೇಡಿ — CatalogListResponse ಎನ್‌ವೆಲಪ್ ಅನ್ನು ಬಿಟ್ಟುಬಿಡುವುದು api_version, total ಮತ್ತು offset ಅನ್ನು ತೆಗೆದುಹಾಕುತ್ತದೆ, ಇದರಿಂದ ಗ್ರಾಹಕರಿಗೆ ಸ್ಕೀಮಾ ಬದಲಾವಣೆಗಳನ್ನು ಪತ್ತೆಹಚ್ಚಲು ಅಥವಾ ಪೇಜಿನೇಷನ್ ಅನ್ನು ನಡೆಸಲು ಯಾವುದೇ ಮಾರ್ಗ ಉಳಿಯುವುದಿಲ್ಲ, ಇದು API ಮುಚ್ಚಲು ಉದ್ದೇಶಿಸಿರುವ ಅದೇ ಕಂಡುಹಿಡಿಯುವಿಕೆಯ ಅಂತರ.
3. ಕಾಣೆಯಾದ service_id ಗಾಗಿ get_service ನಿಂದ return None ಮಾಡಬೇಡಿ — ಶೂನ್ಯ ದೇಹವು null ನೊಂದಿಗೆ 200 ಆಗಿ ಸೀರಿಯಲೈಸ್ ಆಗಿ ದೋಷವನ್ನು ಮರೆಮಾಡುತ್ತದೆ; HTTPException(status_code=404, ...) ಅನ್ನು raise ಮಾಡುವುದು ಗ್ರಾಹಕರಿಗೆ ಕ್ರಮಕೈಗೊಳ್ಳಬಹುದಾದ, ಸರಿಯಾಗಿ ಕೋಡ್ ಮಾಡಲಾದ, ಅವರು ಕವಲೊಡೆಯಬಹುದಾದ ವೈಫಲ್ಯವನ್ನು ನೀಡುತ್ತದೆ.