தேடல் மற்றும் வடிகட்டலுடன் service catalog REST API ஐ உருவாக்குதல்

அறிமுகம்

நீங்கள் ஒரு சேவை பட்டியலை (service catalog) வெளியிட்டு, ஆனால் அதை நிரல்முறையாக வினவ (query) நுகர்வோருக்கு எந்த வழியும் வழங்காதபோது, குழுக்கள் Git ரெப்போவில் உள்ள மூல YAML-ஐப் படிப்பது, Slack செய்திகளை ஸ்கிரீன்ஷாட் எடுப்பது, அல்லது "நாம் என்ன வெக்டர் தரவுத்தளங்களை வழங்குகிறோம்?" என்று ஒரு டிக்கெட்டில் தள குழுவிடம் கேட்பது போன்ற வழிகளுக்குத் திரும்புகின்றன. பட்டியல் தரவு இருக்கிறது, ஆனால் அது கண்டறியத்தக்கதாக இல்லை—"team-beta-க்குச் சொந்தமான ஒவ்வொரு GPU-ஆதரவு மாடல்-சர்விங் உள்ளீட்டையும், புதிய பதிப்பு முதலில் வரும் வரிசையில் காட்டு" என்ற கேள்விக்கு ஒரு மனிதரின் தலையீடு இல்லாமல் பொறியாளர்கள் பதிலளிக்க முடியாது. API அடுக்கு இந்த இடைவெளியை நிறைவு செய்கிறது: கட்டமைக்கப்பட்ட தேடல், வகை வடிகட்டல், பக்கமாக்கல் (pagination), மற்றும் வெளிப்படையான பதில் பதிப்பு ஆகியவற்றுடன் HTTP வழியாகப் பட்டியலை வெளிப்படுத்துகிறது, இதனால் டெவலப்பர் போர்ட்டல்கள், CLI-கள், மற்றும் CI பைப்லைன்கள் அனைத்தும் ஒரே ஒப்பந்தத்தை (contract) நுகர முடியும். இந்தப் பாடத்தின் முடிவில், நுகர்வோர் உள்ளீட்டைச் சரிபார்க்கும் வினவல் மற்றும் பதில் ஸ்கீமாக்களை வரையறுக்கவும், பட்டியல் சேமிப்பகத்தின் மீது இயங்கும் முழு-உரைத் தேடல் மற்றும் வகை வடிகட்டியை செயல்படுத்தவும், ஏற்கனவே உள்ள கிளையன்ட்களை உடைக்காமல் payload வடிவத்தை மேம்படுத்த அனுமதிக்கும் பதிப்பிடப்பட்ட உறையில் (versioned envelope) முடிவுகளைப் பொதியவும் உங்களால் முடியும்.

முக்கிய சொற்கள்

• Catalog API: சேவை பட்டியலின் மீதான வாசிப்புச் செயல்பாடுகளை—பட்டியலிடுதல், தேடுதல், வடிகட்டுதல், மற்றும் தனிப்பட்ட உள்ளீடுகளைப் பெறுதல்—தள நுகர்வோருக்கு வெளிப்படுத்தும் HTTP இடைமுகம்.
• Query Parameter Model: URL வினவல் சர ஆர்குமென்ட்களை வகை வரையறுக்கப்பட்ட புலங்களுடன் பிணைக்கும், சேமிப்பக அணுகலுக்கு முன்பே தவறான கோரிக்கைகளை நிராகரிக்கும் ஒரு சரிபார்க்கப்பட்ட ஸ்கீமா (CatalogQuery).
• Response Envelope: முடிவு உருப்படிகளுடன் சேர்த்து மொத்த எண்ணிக்கை, பக்கமாக்கல் கர்சர், மற்றும் API பதிப்பு போன்ற மெட்டாடேட்டாவையும் சுமந்து செல்லும் ஒரு உறை ஆப்ஜெக்ட் (CatalogListResponse).
• API Versioning: ஒவ்வொரு பதிலிலும் வெளிப்படையான api_version புலத்தை உட்பொதித்தல், இதனால் நுகர்வோர் அமைதியாக உடைவதற்குப் பதிலாக ஸ்கீமா மாற்றங்களைக் கண்டறிந்து அவற்றுக்கு ஏற்ப மாறிக்கொள்ள முடியும்.
• Category Filter: ஒரு ServiceCategory-க்குப் பொருந்தும் உள்ளீடுகளுக்கு முடிவுகளைச் சுருக்கும் சர்வர்-பக்க predicate; எண்ணிக்கைகள் துல்லியமாக இருக்கும்படி பக்கமாக்கலுக்கு முன்பு பயன்படுத்தப்படுகிறது.

கருத்துகள்

இப்போது நம்மிடம் வெளிப்படுத்த ஒரு பட்டியல் தரவு மாடல் இருப்பதால், API அடுக்கு தள நுகர்வோருக்கும் அடிப்படை உள்ளீட்டுச் சேமிப்பகத்துக்கும் இடையில் அமர்ந்து, தளர்வாக வகைப்படுத்தப்பட்ட HTTP வினவல் சரங்களைச் சரிபார்க்கப்பட்ட, வடிகட்டப்பட்ட, பதிப்பிடப்பட்ட பதில்களாக மொழிபெயர்க்கிறது. ஒரு கோரிக்கை நான்கு நிலைகள் வழியாகப் பாய்கிறது: உள்ளீட்டுப் பிணைப்பு (input binding), வடிகட்டல், பக்கமாக்கல், மற்றும் உறை உருவாக்கம். ஒவ்வொரு நிலைக்கும் ஒரே ஒரு பொறுப்பு உள்ளது, அவற்றைத் தனித்தனியாக வைத்திருப்பதே தேடல் endpoint-ஐ சோதிக்கத்தக்கதாகவும் பதில் வடிவத்தை மேம்படுத்தத்தக்கதாகவும் ஆக்குகிறது.

உள்ளீட்டுப் பிணைப்பு நிலை ?q=qdrant&category=vector-db&limit=20&offset=0-ஐ ஒரு CatalogQuery instance-க்கு வரைபடமாக்குகிறது. வகை வரையறுக்கப்பட்ட மாடல் வழியாகப் பிணைப்பது என்பது, ஒரு செல்லுபடியாகாத limit (எதிர்மறை, அல்லது உச்சவரம்பிற்கு மேல்) தானாகவே 422 உடன் நிராகரிக்கப்படும் என்பதாகும்—endpoint-இன் உடல் தவறான உள்ளீட்டின் மீது ஒருபோதும் இயங்காது. வடிகட்டல் நிலை இரண்டு சுயாதீனமான predicate-களைப் பயன்படுத்துகிறது: q சொல்லுக்காக உள்ளீட்டின் name மற்றும் description-க்கு எதிராக case-insensitive substring பொருத்தம், மற்றும் category-க்காகச் சரியான service_type பொருத்தம். இரண்டுமே விருப்பத்தேர்வு; ஏதேனும் ஒன்றைத் தவிர்ப்பது பிழை ஏற்படுத்துவதற்குப் பதிலாக முடிவுத் தொகுப்பை விரிவுபடுத்துகிறது.

கடைசி இரண்டு நிலைகளுக்கு இடையே வரிசை முக்கியம். total எல்லா உள்ளீடுகளின் எண்ணிக்கையை அல்ல, பொருந்தும் உள்ளீடுகளின் எண்ணிக்கையைப் பிரதிபலிக்க வேண்டும் என்பதால், பக்கமாக்கலுக்கு முன்பு வடிகட்டல் முடிவடைய வேண்டும். நீங்கள் முதலில் பக்கமாக்கி, பின்னர் பக்கத்தை வடிகட்டினால், ஒரு தேடலின் இரண்டாம் பக்கம் முதல் பக்கத்தில் விழுந்த பொருத்தங்களை அமைதியாக இழக்கிறது, மேலும் மொத்தம் அர்த்தமற்றதாகிறது. முழுத் தொகுப்பின் மீதும் apply_filters-ஐ இயக்கி, வடிகட்டப்பட்ட நீளத்திலிருந்து total-ஐக் கணக்கிட்டு, அதன் பிறகுதான் paginate மூலம் துண்டாக்குவது பக்கமாக்கல் மெட்டாடேட்டாவை நேர்மையாக வைத்திருக்கிறது.

பதில் உறையே பதிப்பிடல் வாழும் இடம். ஒரு வெற்று JSON அணிவரிசையைத் திருப்புவதற்குப் பதிலாக, list_services ஒரு CatalogListResponse-ஐத் திருப்புகிறது, அது api_version, items, total, limit, மற்றும் offset-ஐச் சுமந்து செல்கிறது. நுகர்வோர் payload-ஐப் புரிந்துகொள்கிறார்களா என்பதைத் தீர்மானிக்க api_version-ஐப் படிக்கிறார்கள். பின்னர் நீங்கள் ஒரு புலத்தைச் சேர்க்கும்போது—உதாரணமாக ஒரு deprecation_notice—api_version "v1"-ஐப் பின்பற்றிய பழைய கிளையன்ட்கள் தொடர்ந்து வேலை செய்கின்றன, ஏனெனில் ஒரு பதிப்பிற்குள் கூட்டல் மாற்றங்கள் பாதுகாப்பானவை, மேலும் ஒரு உடைக்கும் மாற்றம் பதிப்பை உயர்த்துகிறது, இதனால் கிளையன்ட்கள் அதன் அடிப்படையில் கிளைபிரிய முடியும். இது பட்டியல் உள்ளீடுகளுக்கே நீங்கள் பயன்படுத்தும் அதே ஒழுக்கமுறை, போக்குவரத்து அடுக்குக்கு நீட்டிக்கப்பட்டது.

குறியீடு விளக்கம்

நான்கு-நிலை கோரிக்கைப் பாய்வை மதிப்பாய்வு செய்த பிறகு, பின்வரும் செயலாக்கம் அதை இரண்டு பகுதிகளாகக் குறியாக்குகிறது: HTTP ஒப்பந்தத்தைப் பிணைத்துச் சரிபார்க்கும் கோரிக்கை/பதில் ஸ்கீமாக்கள், மற்றும் தேடல், வடிகட்டல், பக்கமாக்கல் ஆகியவற்றை இரண்டு endpoint-களில் இணைக்கும் FastAPI router. முதல் பிளாக் ServiceCategory, CatalogQuery உள்ளீட்டு மாடல், ஒவ்வொரு உருப்படிக்குமான CatalogItemResponse, மற்றும் பதிப்பிடப்பட்ட CatalogListResponse உறையை வரையறுக்கிறது—தவறான கோரிக்கைகள் handler-இன் ஆழத்தில் அல்லாமல் பிணைப்பு நேரத்திலேயே தோல்வியடையும் வகையில் ஒவ்வொரு புலமும் கட்டுப்படுத்தப்பட்டுள்ளது.

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 வினவல் அளவுரு பிணைப்பிலேயே நிராகரிக்கப்படுகிறது—handler-க்குள் அதைக் கையால் சரிபார்க்கத் தேவையில்லை.
• வரிகள் 14-18: CatalogQuery limit-ஐ [1, 100]-க்கும் offset-ஐ ≥ 0-க்கும் வரம்பிடுகிறது. limit=5000 கேட்கும் ஒரு கிளையன்ட் 422-ஐப் பெறுகிறது, இது வரம்பற்ற ஸ்கேன்களிலிருந்து சேமிப்பகத்தைப் பாதுகாக்கிறது; இரு தேடல் புலங்களும் இயல்பாக None ஆக இருப்பதால், ஆர்குமென்ட் இல்லாத ஒரு கோரிக்கை எல்லாவற்றின் முதல் பக்கத்தைத் திருப்புகிறது.
• வரிகள் 28-33: CatalogListResponse api_version-ஐ இயல்பாக CATALOG_API_VERSION ஆக அமைக்கிறது, எனவே ஒவ்வொரு பதிலும் தன்னை விவரிக்கும் தன்மை கொண்டது; total items-க்கு அருகில் அமர்ந்திருப்பதால், நுகர்வோர் இரண்டாவது அழைப்பு இல்லாமல் இன்னும் எத்தனை பக்கங்கள் மீதமுள்ளன என்பதைக் கணக்கிட முடியும்.

இரண்டாவது பிளாக் வடிகட்டல் மற்றும் பக்கமாக்கல் pure function-களையும் இரண்டு endpoint-களையும் செயல்படுத்துகிறது. apply_filters முழு உள்ளீட்டுத் தொகுப்பின் மீதும் இரு predicate-களையும் இயக்குகிறது; 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 முதலில் வகை predicate-ஐ (குறைந்த செலவுள்ள சரியான பொருத்தம்) பயன்படுத்தி, பின்னர் substring தேடலைப் பயன்படுத்துகிறது; இரண்டும் is not None / truthiness மூலம் பாதுகாக்கப்படுவதால், தவிர்க்கப்பட்ட ஒரு அளவுரு எதையும் வடிகட்டாமல் முடிவுகளை விரிவுபடுத்தும் no-op ஆகிறது.
• வரிகள் 22-30: list_services முழுத் தொகுப்பின் மீதும் matched-ஐக் கணக்கிட்டு, துண்டாக்குவதற்கு முன்பு len(matched)-இலிருந்து total-ஐப் பெற்று, பின்னர் பக்கமாக்குகிறது—இது உறையின் total மூலப் பட்டியல் அளவை அல்ல, பொருத்தங்களை எண்ணுவதை உறுதி செய்கிறது.
• வரிகள் 33-38: get_service ஒற்றை உள்ளீட்டைத் திருப்புகிறது அல்லது 404 உடன் ஒரு HTTPException-ஐ raise செய்கிறது; None-ஐத் திருப்புவது FastAPI ஒரு null உடலை serialize செய்ய அனுமதிக்கும், எனவே வெளிப்படையான 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-ஒப்பந்த மற்றும் தேடல்-சரியான தன்மை வடிவங்களை உங்கள் சொந்தப் பட்டியல் endpoint-களை உருவாக்கும்போது நேரடியாகப் பயன்படுத்தக்கூடிய விதிகளாகச் சுருக்கித் தருகின்றன.

செய்ய வேண்டியவை

1. Depends() உடன் CatalogQuery மாடல் வழியாக வினவல் சரங்களைப் பிணைக்கவும் — Field கட்டுப்பாடுகள் (limit [1, 100]-க்குள், offset ≥ 0, category ஒரு ServiceCategory ஆக) list_services இயங்குவதற்கு முன்பே தவறான கோரிக்கைகளை 422 உடன் நிராகரிக்கின்றன, எனவே வரம்பற்ற limit அல்லது தெரியாத வகைச் சரத்தின் மீது எந்த handler குறியீடும் ஒருபோதும் இயங்காது.
2. முழு உள்ளீட்டுத் தொகுப்பின் மீதும் apply_filters-ஐ இயக்கி, paginate-ஐ அழைப்பதற்கு முன்பு len(matched)-இலிருந்து total-ஐப் பெறவும் — வடிகட்டப்பட்ட-ஆனால்-துண்டாக்கப்படாத பட்டியலின் மீது எண்ணிக்கையைக் கணக்கிடுவது CatalogListResponse.total புலத்தை நேர்மையாக வைத்திருக்கிறது, எனவே நுகர்வோர் பொருத்தங்களை அமைதியாக இழக்காமல் தேடல் முடிவுகளைப் பக்கம் பக்கமாகப் பார்க்க முடியும்.
3. ஒவ்வொரு பதிலையும் CATALOG_API_VERSION-இலிருந்து api_version உடன் முத்திரையிடவும் — தன்னை விவரிக்கும் உறை போர்ட்டல்களையும் CI கிளையன்ட்களையும் பதிப்பின் அடிப்படையில் கிளைபிரிய அனுமதிக்கிறது, மேலும் உடைக்கும் payload மாற்றங்களுக்குப் பதிப்பு உயர்வை ஒதுக்கி வைத்து, "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 உடல் null உடன் 200 ஆக serialize ஆகி, பிழையை மறைக்கிறது; HTTPException(status_code=404, ...)-ஐ raise செய்வது நுகர்வோருக்கு அவர்கள் கிளைபிரியக்கூடிய, செயல்படுத்தத்தக்க, சரியாகக் குறியிடப்பட்ட தோல்வியை வழங்குகிறது.