🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
chore(api): mark v3 apis as deprecated in openai (#16099)
Nimar85e179dc50b4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2aa334f455..4ae80117fe 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -538,11 +538,11 @@ We maintain the API specifications manually to guarantee a high degree of undersTo export the respective `openapi.yml` files which power the online API reference, run:```sh-npx fern-api export --api server web/public/generated/api/openapi.yml-npx fern-api export --api client web/public/generated/api-client/openapi.yml-npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml+pnpm run openapi:export```+This command also syncs standard OpenAPI `deprecated` flags from the endpoint `availability` metadata in the Fern definitions.+To generate the server SDKs, run:```shdiff --git a/package.json b/package.jsonindex 79ccb84830..71c6a789ff 100644--- a/package.json+++ b/package.json@@ -38,6 +38,7 @@"format": "prettier --write \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli","format:check": "prettier --check \"**/*.{js,jsx,ts,tsx,css}\" --experimental-cli","playwright:install": "pnpm --filter web exec playwright install chromium",+ "openapi:export": "npx fern-api export --api server web/public/generated/api/openapi.yml && pnpm --filter web exec tsx scripts/openapi/sync-deprecations.ts && npx fern-api export --api client web/public/generated/api-client/openapi.yml && npx fern-api export --api organizations web/public/generated/organizations-api/openapi.yml","storybook": "pnpm --filter web run storybook","test": "turbo run test","release": "bash ./scripts/release-preflight.sh && dotenv -e ../.env -- release-it",diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex 347afcbb5f..dd5f1517e4 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -1179,6 +1179,7 @@ paths:application/json:schema:$ref: '#/components/schemas/CreateDatasetRunItemRequest'+ deprecated: trueget:description: List dataset run itemsoperationId: datasetRunItems_list@@ -1242,6 +1243,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/v2/datasets:get:description: Get all datasets@@ -1436,6 +1438,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: truedelete:description: Delete a dataset run and all its run items. This action is irreversible.operationId: datasets_deleteRun@@ -1485,6 +1488,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/datasets/{datasetName}/runs:get:description: Get dataset runs@@ -1544,6 +1548,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/experiments:get:description: |-@@ -1985,6 +1990,7 @@ paths:debugging.required:- batch+ deprecated: true/api/public/metrics:get:description: >-@@ -2086,6 +2092,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/observations/{observationId}:get:description: Get a observation@@ -2134,6 +2141,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/observations:get:description: >-@@ -2422,6 +2430,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/scores/{scoreId}:delete:description: Delete a score (supports both trace and session scores)@@ -5973,6 +5982,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/v2/scores/{scoreId}:get:description: |-@@ -6023,6 +6033,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/sessions:get:description: >-@@ -6122,6 +6133,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/sessions/{sessionId}:get:description: >-@@ -6180,6 +6192,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: true/api/public/traces/{traceId}:get:description: Get a specific trace@@ -6239,6 +6252,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: truedelete:description: Delete a specific traceoperationId: trace_delete@@ -6611,6 +6625,7 @@ paths:application/json:schema: {}security: *ref_0+ deprecated: truedelete:description: Delete multiple tracesoperationId: trace_deleteMultiplediff --git a/web/scripts/openapi/fern-deprecations.ts b/web/scripts/openapi/fern-deprecations.tsnew file mode 100644index 0000000000..f17d916818--- /dev/null+++ b/web/scripts/openapi/fern-deprecations.ts@@ -0,0 +1,93 @@+import fs from "node:fs";+import path from "node:path";+import { parse } from "yaml";++type FernAvailability =+ | string+ | {+ status?: string;+ };++type FernDefinition = {+ "base-path"?: string;+ service?: {+ "base-path"?: string;+ endpoints?: Record<+ string,+ {+ availability?: FernAvailability;+ "base-path"?: string;+ method?: string;+ path?: string;+ }+ >;+ };+};++export type DeprecatedOperation = {+ method: string;+ endpointPath: string;+};++function listYamlFiles(directory: string): string[] {+ return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {+ const entryPath = path.join(directory, entry.name);++ if (entry.isDirectory()) return listYamlFiles(entryPath);+ if (entry.isFile() && /\.ya?ml$/.test(entry.name)) return [entryPath];+ return [];+ });+}++function joinApiPath(...parts: Array<string | undefined>): string {+ return `/${parts+ .filter((part): part is string => Boolean(part))+ .map((part) => part.replace(/^\/+|\/+$/g, ""))+ .filter(Boolean)+ .join("/")}`;+}++function isDeprecated(availability: FernAvailability | undefined): boolean {+ return (+ availability === "deprecated" ||+ (typeof availability === "object" && availability.status === "deprecated")+ );+}++export function getFernDeprecatedOperations(+ definitionDirectory: string,+): DeprecatedOperation[] {+ const apiDefinition = parse(+ fs.readFileSync(path.join(definitionDirectory, "api.yml"), "utf8"),+ ) as FernDefinition;++ return listYamlFiles(definitionDirectory).flatMap((definitionPath) => {+ const definition = parse(+ fs.readFileSync(definitionPath, "utf8"),+ ) as FernDefinition;+ const service = definition.service;++ if (!service?.endpoints) return [];++ return Object.values(service.endpoints).flatMap((endpoint) => {+ if (!isDeprecated(endpoint.availability)) return [];+ if (!endpoint.method || endpoint.path === undefined) {+ throw new Error(+ `Deprecated endpoint in ${definitionPath} must define method and path`,+ );+ }++ return [+ {+ method: endpoint.method.toLowerCase(),+ endpointPath: joinApiPath(+ apiDefinition["base-path"],+ service["base-path"],+ endpoint["base-path"],+ endpoint.path,+ ),+ },+ ];+ });+ });+}diff --git a/web/scripts/openapi/sync-deprecations.ts b/web/scripts/openapi/sync-deprecations.tsnew file mode 100644index 0000000000..7de1416e4d--- /dev/null+++ b/web/scripts/openapi/sync-deprecations.ts@@ -0,0 +1,73 @@+import fs from "node:fs";+import path from "node:path";+import { isMap, parseDocument } from "yaml";++import { getFernDeprecatedOperations } from "./fern-deprecations";++const webDirectory = process.cwd();+const definitionDirectory = path.resolve(+ webDirectory,+ "../fern/apis/server/definition",+);+const openApiPath = path.resolve(+ webDirectory,+ "public/generated/api/openapi.yml",+);++let openApiSource = fs.readFileSync(openApiPath, "utf8");+const openApi = parseDocument(openApiSource);++if (openApi.errors.length > 0) {+ throw new Error(openApi.errors.map((error) => error.message).join("\n"));+}++const deprecatedOperations = getFernDeprecatedOperations(definitionDirectory);+const insertions: Array<{ offset: number; value: string }> = [];++for (const { method, endpointPath } of deprecatedOperations) {+ const operation = openApi.getIn(["paths", endpointPath, method], true);++ if (!isMap(operation)) {+ throw new Error(+ `OpenAPI schema does not contain ${method.toUpperCase()} ${endpointPath}`,+ );+ }++ const deprecated = operation.get("deprecated");+ if (deprecated === true) continue;+ if (deprecated !== undefined) {+ throw new Error(+ `${method.toUpperCase()} ${endpointPath} has an invalid deprecated value`,+ );+ }+ if (!operation.range) {+ throw new Error(+ `Cannot locate ${method.toUpperCase()} ${endpointPath} in the OpenAPI source`,+ );+ }++ const operationLineStart =+ openApiSource.lastIndexOf("\n", operation.range[0]) + 1;+ const insertionOffset =+ openApiSource.lastIndexOf("\n", operation.range[1] - 1) + 1;+ const indentation = openApiSource.slice(+ operationLineStart,+ operation.range[0],+ );++ insertions.push({+ offset: insertionOffset,+ value: `${indentation}deprecated: true\n`,+ });+}++for (const { offset, value } of insertions.sort(+ (left, right) => right.offset - left.offset,+)) {+ openApiSource = `${openApiSource.slice(0, offset)}${value}${openApiSource.slice(offset)}`;+}++fs.writeFileSync(openApiPath, openApiSource);+console.log(+ `Synced ${deprecatedOperations.length} deprecated OpenAPI operations from Fern definitions.`,+);diff --git a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts b/web/src/__tests__/server/unit/openapi-deprecations.servertest.tsnew file mode 100644index 0000000000..a4fb3d3f2b--- /dev/null+++ b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts@@ -0,0 +1,71 @@+import fs from "node:fs";+import os from "node:os";+import path from "node:path";+import { parse } from "yaml";++import { getFernDeprecatedOperations } from "../../../../scripts/openapi/fern-deprecations";++type OpenApiDocument = {+ paths: Record<string, Record<string, { deprecated?: boolean }>>;+};++const definitionDirectory = path.resolve(+ process.cwd(),+ "../fern/apis/server/definition",+);+const openApiPath = path.resolve(+ process.cwd(),+ "public/generated/api/openapi.yml",+);++describe("OpenAPI deprecations", () => {+ it("matches the deprecated endpoints in the Fern definitions", () => {+ const openApi = parse(fs.readFileSync(openApiPath, "utf8"), {+ maxAliasCount: -1,+ }) as OpenApiDocument;+ const openApiDeprecatedOperations = Object.entries(openApi.paths).flatMap(+ ([endpointPath, pathItem]) =>+ Object.entries(pathItem).flatMap(([method, operation]) =>+ operation.deprecated ? [`${method} ${endpointPath}`] : [],+ ),+ );++ expect(openApiDeprecatedOperations.sort()).toEqual(+ getFernDeprecatedOperations(definitionDirectory)+ .map(({ method, endpointPath }) => `${method} ${endpointPath}`)+ .sort(),+ );+ });++ it("supports deprecated endpoints at a service base path", () => {+ const fixtureDirectory = fs.mkdtempSync(+ path.join(os.tmpdir(), "fern-deprecations-"),+ );++ try {+ fs.writeFileSync(+ path.join(fixtureDirectory, "api.yml"),+ "base-path: /api\n",+ );+ fs.writeFileSync(+ path.join(fixtureDirectory, "service.yml"),+ [+ "service:",+ " base-path: /public",+ " endpoints:",+ " get:",+ " availability: deprecated",+ " method: GET",+ ' path: ""',+ "",+ ].join("\n"),+ );++ expect(getFernDeprecatedOperations(fixtureDirectory)).toEqual([+ { method: "get", endpointPath: "/api/public" },+ ]);+ } finally {+ fs.rmSync(fixtureDirectory, { recursive: true });+ }+ });+});diff --git a/web/src/features/README.md b/web/src/features/README.mdindex 84415965a3..025663d75f 100644--- a/web/src/features/README.md+++ b/web/src/features/README.md@@ -21,7 +21,7 @@ TestingAPI Reference- Add to `fern` including `docs` attributes-- Export with `npx fern-api export --api server web/public/generated/api/openapi.yml` and `npx fern-api export --api client web/public/generated/api-client/openapi.yml`, then commit the changes to the API reference+- Export with `pnpm run openapi:export`, then commit the changes to the API referenceSDKs