Skip to content

docs: Mark APIs in /unstable-api as experimental and unstable #233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 15, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions api/pages/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,10 @@ import { pooledMap } from "@std/async/pool";
import { range } from "@core/iterutil/range";
import { flatten } from "@core/iterutil/async/flatten";

/** Options for {@linkcode get} */
/** Options for {@linkcode get}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface ListPagesOption<R extends Response | undefined>
extends BaseOptions<R> {
/** the sort of page list to return
Expand Down Expand Up @@ -57,6 +60,8 @@ export interface ListPagesOption<R extends Response | undefined>
}

/** Constructs a request for the `/api/pages/:project` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name to list pages from
* @param options - Additional configuration options (sorting, pagination, etc.)
Expand Down Expand Up @@ -85,6 +90,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Lists pages from a specified project
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name to list pages from
* @param options Configuration options for pagination and sorting
Expand Down Expand Up @@ -117,7 +124,11 @@ export const get = <R extends Response | undefined = Response>(
}, R>
>;

/** Options for {@linkcode list} */
/**
* Options for {@linkcode list}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface ListPagesStreamOption<R extends Response | undefined>
extends ListPagesOption<R> {
/** The number of requests to make concurrently
Expand All @@ -130,6 +141,8 @@ export interface ListPagesStreamOption<R extends Response | undefined>
/**
* Lists pages from a given `project` with pagination
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name to list pages from
* @param options Configuration options for pagination and sorting
* @throws {HTTPError | TypedError<"NotLoggedInError" | "NotMemberError" | "NotFoundError">} If any requests in the pagination sequence fail
Expand Down
4 changes: 4 additions & 0 deletions api/pages/project/replace/links.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import { cookie } from "../../../../rest/auth.ts";
import { get } from "../../../users/me.ts";

/** Constructs a request for the `/api/pages/:project/replace/links` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project - The project name where all links will be replaced
* @param from - The original link text to be replaced
Expand Down Expand Up @@ -39,6 +41,8 @@ export const makePostRequest = <R extends Response | undefined>(
};

/** Retrieves JSON data for a specified page
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project - The project name where all links will be replaced
* @param from - The original link text to be replaced
Expand Down
4 changes: 4 additions & 0 deletions api/pages/project/search/query.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts";
import { cookie } from "../../../../rest/auth.ts";

/** Constructs a request for the `/api/pages/:project/search/query` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The name of the project to search within
* @param query The search query string to match against pages
Expand All @@ -31,6 +33,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Search for pages within a specific project
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The name of the project to search within
* @param query The search query string to match against pages
Expand Down
12 changes: 11 additions & 1 deletion api/pages/project/search/titles.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,20 @@ import {
type TypedError,
} from "../../../../error.ts";

/** Options for {@linkcode get} */
/**
* Options for {@linkcode get}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface GetLinksOptions<R extends Response | undefined>
extends BaseOptions<R> {
/** ID indicating the next list of links */
followingId?: string;
}

/** Create a request to `GET /api/pages/:project/search/titles`
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project to get the links from
* @param options - Additional configuration options
Expand All @@ -42,6 +48,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Retrieve link data from a specified Scrapbox project
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* This function fetches link data from a project, supporting pagination through
* the {@linkcode GetLinksOptions.followingId} parameter. It returns both the link data and the next
Expand Down Expand Up @@ -76,6 +84,8 @@ export const get = <R extends Response | undefined = Response>(
>;

/** Retrieve all link data from a specified project one by one
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name to list pages from
* @param options Additional configuration options for the request
Expand Down
10 changes: 9 additions & 1 deletion api/pages/project/title.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ import { type BaseOptions, setDefaults } from "../../../util.ts";
import { encodeTitleURI } from "../../../title.ts";
import { cookie } from "../../../rest/auth.ts";

/** Options for {@linkcode getPage} */
/**
* Options for {@linkcode getPage}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface GetPageOption<R extends Response | undefined>
extends BaseOptions<R> {
/** use `followRename` */
Expand All @@ -20,6 +24,8 @@ export interface GetPageOption<R extends Response | undefined>
}

/** Constructs a request for the `/api/pages/:project/:title` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand All @@ -45,6 +51,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Retrieves JSON data for a specified page
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand Down
10 changes: 9 additions & 1 deletion api/pages/project/title/icon.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,20 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts";
import { encodeTitleURI } from "../../../../title.ts";
import { cookie } from "../../../../rest/auth.ts";

/** Options for {@linkcode get} */
/**
* Options for {@linkcode get}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface GetIconOption<R extends Response | undefined>
extends BaseOptions<R> {
/** use `followRename` */
followRename?: boolean;
}

/** Constructs a request for the `/api/pages/:project/:title/icon` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand All @@ -38,6 +44,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Retrieves a specified page image
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand Down
10 changes: 9 additions & 1 deletion api/pages/project/title/text.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,20 @@ import { type BaseOptions, setDefaults } from "../../../../util.ts";
import { encodeTitleURI } from "../../../../title.ts";
import { cookie } from "../../../../rest/auth.ts";

/** Options for {@linkcode get} */
/**
* Options for {@linkcode get}
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*/
export interface GetTextOption<R extends Response | undefined>
extends BaseOptions<R> {
/** use `followRename` */
followRename?: boolean;
}

/** Constructs a request for the `/api/pages/:project/:title/text` endpoint
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand All @@ -38,6 +44,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** Retrieves a specified page text
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project The project name containing the desired page
* @param title The page title to retrieve (case insensitive)
Expand Down
4 changes: 4 additions & 0 deletions api/projects/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ import { type BaseOptions, setDefaults } from "../../util.ts";
import { cookie } from "../../rest/auth.ts";

/** Create a request to `GET /api/projects/:project`
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project - Project name to retrieve information for
* @param options - Additional configuration options
Expand All @@ -33,6 +35,8 @@ export const makeGetRequest = <R extends Response | undefined>(
* access level, settings, and metadata. The returned data type depends on
* whether the user has member access to the project.
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param project - Project name to retrieve information for
* @param options Additional configuration options for the request
* @returns A {@linkcode Response} object containing the project data
Expand Down
4 changes: 4 additions & 0 deletions api/users/me.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import { cookie } from "../../rest/auth.ts";
* This endpoint retrieves the current user's profile information,
* which can be either a {@linkcode MemberUser} or {@linkcode GuestUser} profile.
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param init - Options including `connect.sid` (session ID) and other configuration
* @returns A {@linkcode Request} object for fetching user profile data
*/
Expand All @@ -22,6 +24,8 @@ export const makeGetRequest = <R extends Response | undefined>(
};

/** get the user profile
*
* @experimental **UNSTABLE**: New API, yet to be vetted.
*
* @param init - Options including `connect.sid` (session ID) and other configuration
* @returns A {@linkcode Response} object containing the user profile data
Expand Down