Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(api): mark v3 apis as deprecated in openai (#16099)

Nimar85e179dc50b4
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 unders
To 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:
```sh
diff --git a/package.json b/package.json
index 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.yml
index 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: true
get:
description: List dataset run items
operationId: 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: true
delete:
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: true
delete:
description: Delete a specific trace
operationId: trace_delete
@@ -6611,6 +6625,7 @@ paths:
application/json:
schema: {}
security: *ref_0
+ deprecated: true
delete:
description: Delete multiple traces
operationId: trace_deleteMultiple
diff --git a/web/scripts/openapi/fern-deprecations.ts b/web/scripts/openapi/fern-deprecations.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.md
index 84415965a3..025663d75f 100644
--- a/web/src/features/README.md
+++ b/web/src/features/README.md
@@ -21,7 +21,7 @@ Testing
API 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 reference
SDKs