Open API pro ChatGPT

Přehled: proč je Open API klíčové pro „SEO pro ChatGPT“

Když generativní modely (např. ChatGPT) přistupují k externím službám, rozhodují se na základě popisu API, předvídatelnosti odpovědí a spolehlivosti. „SEO optimalizace pro ChatGPT“ proto neznamená jen tradiční on-page techniky, ale především to, jak je vaše OpenAPI/Swagger schéma navrženo, zda má stabilní endpointy, srozumitelnou sémantiku a jasně komunikované limity. Cílem je, aby model dokázal: (1) vybrat správný endpoint, (2) sestavit validní požadavek, (3) správně interpretovat odpověď bez nejasností a (4) deterministicky zvládnout chybové a hraniční situace.

OpenAPI/Swagger jako „index“ pro LLM

Jednoznačné operationId: musí být stabilní, snadno zapamatovatelné a mapované na úkoly v přirozeném jazyce (např. searchArticles místo getV2).
Semantické tags: používejte doménové skupiny (např. products, orders, auth), aby agent rychle omezil prostor výběru.
Popisy s úmyslem: v summary a description popisujte „pro co“ a „kdy ne“; model ocení negativní příklady a kontrasty (disambiguaci).
Formální omezení: enum, pattern, minLength, maximum redukují prostor pro chyby při generování požadavků.
Příklady (examples): krátké, realistické, s minimem irelevantních polí; doplňte také chybové vzorky (např. 400, 429, 503).

Stabilita endpointů: verzování, kontrakty a změnové politiky

Verzování v cestě nebo hlavičce: /v1/ je pro LLM nejčitelnější; při přechodu na /v2/ ponechte /v1/ s jasným deprekačním oknem (např. 6–12 měsíců).
Kontrakt je závazek: neměňte význam polí bez změny verze; nová pole přidávejte jako volitelná s výchozím chováním.
Changelog s daty: stručný log s příklady před/po pomáhá agentům přizpůsobit promptování.
Deterministická serializace: pořadí polí v odpovědi zachovejte konzistentní; snižuje „halucinace“ parserů.

Terminologie a modelování zdrojů: „čitelné“ pro lidi i modely

Resource-oriented design: používejte podstatná jména v množném čísle a HTTP metody předvídatelně (GET /articles, POST /orders).
Vyhněte se „mega“ endpointům: raději více úzce zaměřených operací než jeden polymorfní endpoint s desítkami parametrů.
Konzistentní ID a formáty: id jako řetězec, timestampy v RFC 3339, měnové hodnoty v minoritních jednotkách (např. centech) s polem měny.
Idempotence: PUT/DELETE idempotentní, POST podporované Idempotency-Key pro bezpečné opakování agentů.

Specifikace schémat: přesnost, volitelnost, degradace

Minimální povinná pole: definujte required pouze to, co je skutečně nezbytné; zbytek volitelný s jasnými výchozími hodnotami.
Přísné typy: nepoužívejte generické object, pokud znáte strukturu; vyhněte se anyOf, pokud není nutné.
Zpětně kompatibilní rozšiřování: nové enum hodnoty oznamujte v changelogu a popisujte je v description.

Dokumentační styl pro LLM: „promptability“ vaší OpenAPI schématu

Strukturované úkoly v description: větou začněte „Použij tento endpoint, pokud chceš…“ a přidejte 2–3 kontraindikace „Nepoužívej, když…“.
Explicitní předpoklady: autentifikace, nutné kapacity, pořadí volání (např. „nejprve získej token, potom volej /me“).
Mini-playbook: pro komplexní domény vložte „sekvence“ (např. vyhledání → detail → checkout) jako krátké scénáře.
Jazyk bez nejednoznačnosti: vyhýbejte se metaforám; preferujte definice s jednoznačným slovníkem.

Limity a kvóty: jak je navrhnout a komunikovat

Standardizované odpovědi 429: vraťte Retry-After, aktuální spotřebu a okno; do těla zahrňte strojově čitelná pole (limit, remaining, resetAt).
Granularita kvót: rozlišujte per-user, per-token, per-IP; uveďte také burst limity a dlouhodobá okna.
Velikostní limity: maxima pro počet položek na stránku, velikost těla, počet filtrů; při překročení vracejte 413/400 s doporučením, jak požádat o méně.
Časové limity: interní SLA (např. P95 < 300 ms) a časové prahové hodnoty pro timeouty; explicitně popište, kdy se vyplatí použít asynchronní vzor.

Stránkování, filtrování, třídění: vzory přátelské k LLM

Cursor-based stránkování: pole nextCursor, prevCursor; vyhněte se nejednoznačnému offset u mutujících datasetů.
Výchozí pořadí: deterministické (createdAt desc); vysvětlete v popisu.
Bezpečné filtry: whitelistování parametrů; pro fuzzy dotazy poskytněte jedno q pole s omezeními délky.

Autentifikace a autorizace: jasnost pro agenta

OpenAPI securitySchemes: názvy typu ApiKeyAuth, OAuth2ClientCredentials; popište granty a rozsahy.
Scope-driven design: každý endpoint deklaruje minimální potřebné scopy; agent tak ví, jaká oprávnění vyžádat.
Rotace tajemství: komunikujte expiraci a refresh mechanismus; chybové kódy 401/403 musí být odlišeny textem i kódem chyby.

Chybové zprávy: deterministické, lokalizovatelné, akční

Standardní formát chyby: {code, message, details[], docUrl, correlationId}.
Code je strojový: stabilní, bez diakritiky (např. INVALID_ARGUMENT, RATE_LIMITED).
Message je lidská: krátká, akční, bez interního žargonu; details obsahují pole a pravidla, která selhala.
DocUrl: odkazuje na konkrétní sekci dokumentace k chybě.

Kešování, čerstvost a verifikovatelnost

ETag a Last-Modified: umožněte If-None-Match a If-Modified-Since pro úsporu kvót.
Expirační politiky: uveďte maximální stáří dat; u near-real-time dat popište zpoždění (např. „do 60 s“).
Kontrolní součty: hash obsahu v odpovědi zvyšuje důvěru a reprodukovatelnost.

Jasná metadata a discoverability pro ChatGPT

„Úkolové“ tagy: doplňte pole v rozšířeních (např. x-tasks) se seznamem přirozenojazykových úkolů, které endpoint řeší.
„Nákladová“ metadata: x-cost-hints (latence, průměrná velikost odpovědi) pomáhají agentům vybrat levnější cestu.
„Datové garance“: x-sla pro dostupnost, konzistenci, okno aktualizací.

Testování s LLM v „loopu“: jak měřit použitelnost API

Task-success rate: procento případů, kdy model zvolí správný endpoint a vrátí validní požadavek bez manuálních zásahů.
First-call success: míra úspěchu na první pokus; ukazuje kvalitu dokumentace a omezení.
Error-guided repair: zda chybové hlášky vedou model ke správné opravě parametrů.
Hallucination score: frekvence volání neexistujících parametrů/endpointů; snižujte jasnou specifikací a příklady.

Bezpečnost a ochrana údajů v kontextu generativních agentů

Princip nejmenších oprávnění (Least privilege): tokeny s minimálními scopemi a krátkou expirací.
Pseudonymizace: zákaznická ID oddělená od interních primárních klíčů.
Přenos a ukládání: TLS 1.2+, šifrování na disku pro citlivá data; auditovatelné přístupy.
PII režim: jasný parametr nebo oddělené endpointy, které vrací/skryjí osobní údaje; srozumitelné zásady v dokumentaci.

Mezinárodizace a lokalizace odpovědí

Parametry jazyka a regionu: Accept-Language nebo locale parametr; popište podporované hodnoty.
Formáty data, měny: návrat v ISO, formátování ponechte klientovi; předejdete nejasnostem.

Observabilita, monitoring a zpětná smyčka

Correlation: correlationId v požadavku/odpovědi pro sledování toku.
LLM telemetrie: logujte neznámé parametry, nejčastější chyby a dotazy; využijte to ke zlepšení schématu a příkladů.
SLO/SLA: publikujte P95 latenci, chybovost a dostupnost; usnadníte agentům volbu strategie volání.

Praktický „LLM-friendly“ checklist pro OpenAPI

Každý endpoint má jedinečné, úkolové operationId a jasné summary.
Parametry mají enum a pattern, kde je to možné; čísla mají rozsahy.
Odpovědi definují schémata pro 2xx, 4xx, 5xx; chybová těla jsou jednotná.
Příklady obsahují i selhání (400/429) s návodem na opravu.
Stránkování používá kurzory; odpověď vrací nextCursor/hasMore.
Limity jsou komunikovány v hlavičkách i těle; 429 obsahuje Retry-After.
Verze API je v URL; deprekační hlavičky mají datum a doporučení migrace.
Bezpečnostní schémata jsou pojmenovaná a zdokumentovaná; scopy jsou minimální.
Changelog je veřejný a stručný; obsahuje kotvy na dokumentaci.

Vzory pro stabilitu: fallbacky a robustnost

Graceful degradation: při výpadcích vraťte menší, ale konzistentní výstup s jasným příznakem partial=true.
Explicitní výchozí hodnoty: dokumentujte implicitní hodnoty; LLM tak generuje kratší a správnější požadavky.
Idempotentní retry: kombinace Idempotency-Key a bezpečných timeoutů minimalizuje duplicitní záznamy.

Nejčastější chyby při „SEO pro ChatGPT“ v API

Nejednoznačné popisy bez kontrastů („pro vyhledávání“ bez uvedení omezení a negativních příkladů).
Polymorfní schémata bez discriminator nebo s volným object.
Skryté limity a nestandardní chybová těla.
Chybějící příklady pro nejčastější pracovní toky.
Nestabilní pojmenování a nezaznamenané breaking změny.

Metriky úspěchu: jak změřit „optimalizaci pro ChatGPT“

API Task Completion Rate: podíl scénářů, kdy agent vykoná úkol end-to-end bez manuálních zásahů.
Prompt Token Efficiency: průměrný počet tokenů potřebných ke správnému požadavku (nižší je lepší).
Error-to-Fix Latency: čas od chyby k následnému úspěšnému volání.
Schema Coverage: procento endpointů s příklady úspěšných i neúspěšných odpovědí.

Příklady textových vzorů do OpenAPI popisů

Summary (dobrý): „Vyhledá články podle klíčových slov a času publikace. Nepoužívejte pro detail článku.“
Description (dobrý): „Použij, pokud potřebuješ seznam článků pro náhled. Pokud potřebuješ celý obsah, volej getArticleById. Limit