diff --git a/content/guides/api-calls/allowing-domain-access.md b/content/guides/api-calls/allowing-domain-access.md index 356ca421b..31af61ba0 100644 --- a/content/guides/api-calls/allowing-domain-access.md +++ b/content/guides/api-calls/allowing-domain-access.md @@ -11,12 +11,12 @@ alias_paths: - /guides/api-calls/domain-whitelisting --- -# Allowing Domain Access +# Allow domain access To use the Box APIs it is important that your application and users have access to the following domains, where needed. -## File Preview +## File preview To enable file preview, your application might need to load javascript file from the Box content delivery network (CDN). This file is loaded from the following diff --git a/content/guides/api-calls/api-versioning-strategy.md b/content/guides/api-calls/api-versioning-strategy.md index 22b48fcbf..5dc031121 100644 --- a/content/guides/api-calls/api-versioning-strategy.md +++ b/content/guides/api-calls/api-versioning-strategy.md @@ -5,7 +5,7 @@ related_guides: [] required_guides: [] --- -# API Versioning Strategy +# API versioning strategy Box provides versioning capabilities for selected API endpoints. The version control system guarantees seamless functioning of existing endpoint versions, even if Box introduces new ones. @@ -25,24 +25,26 @@ Box API supports versioning in URL `path` and `header`. To determine which versi +### Versioning in `path` + The default version of the API used in any requests is specified in the URL of the endpoint you call. -An example flow looks like this: +For example, when calling the `https://upload.box.com/api/2.0/files/content` endpoint without any version header specified, you reach the `2.0` version defined in the URL. -1. When calling the [upload](`https://upload.box.com/api/2.0/files/content`) endpoint without any version header specified, you hit the `2.0` version defined in the URL. +If there is a significant change to API behavior, the new endpoint will be exposed under the new URL. +For example, `https://upload.box.com/api/2.0/files/content` supports a multipart content type when uploading files to Box. If the new version of this API stops supporting this content type, it will be released under a new URL `https://upload.box.com/api/3.0/files/content`. -2. Box API processes the `box-version` header which should: +### Versioning in `header` - - contain a valid version name, that is `box-version: 2025.0` - - be directed at `https://api.box.com/2.0/files/:file_id/metadata`. +Box API processes the `box-version` header which should contain a valid version name, that is `box-version: 2025.0` and be directed at `https://api.box.com/2.0/files/:file_id/metadata`. -3. If the provided version is correct, a response is sent back to the client. The response also contains the `box-version` header if it was provided in the request. By default, this header is not present in the response. If the version is wrong, an error with the HTTP code `400` is returned to the client. - -If there is a significant change to API behavior, the new endpoint will be exposed under the new URL. -For example, `https://upload.box.com/api/2.0/files/content` supports a multipart content type when uploading files to Box. If the new version of this API stops supporting this content type, it will be released under a new URL `https://upload.box.com/api/3.0/files/content`. +If the provided version is correct, a response is sent back to the client. The response also contains the `box-version` header if it was provided in the request. By default, this header is not present in the response. If the version is wrong, an error with the HTTP code `400` is returned to the client. ## Release schedule and naming convention -Box can introduce a new breaking change to certain endpoints **once per year**. An endpoint encompasses all supported HTTP methods within a specific API root. For example, the Sign Request endpoints include: +Box can introduce a new breaking change to certain endpoints **once per year**. +Introducing a new version of the Sign Request endpoint means that **all paths and HTTP methods** of an endpoint will support it. + +For example, if Sign Request endpoints receive a new version it will apply to all endpoints listed in the table: | Method | Request URL | Description | | ------ | -------------------------------------------------- | ---------------------------------------- | @@ -52,27 +54,39 @@ Box can introduce a new breaking change to certain endpoints **once per year**. | POST | `https://api.box.com/2.0/sign_requests/:id/resend` | Sends a specific sign request again. | | POST | `https://api.box.com/2.0/sign_requests/:id/cancel` | Cancels a specific sign request. | -Introducing a new version of the sign request endpoint means that all paths and HTTP methods listed above will support it. You can find comprehensive information about the endpoint version in the [Box API Reference](https://developer.box.com/reference/). - ### Naming convention New API versions are labeled according to the calendar year of their release. -For example, if a new version of the Sign Requests endpoint is released in 2025, it will be named `2025.0`. -Box can issue a new breaking change to API endpoints once per year, reserving the right to release an additional breaking change to address security or privacy concerns. In such cases, the new version will be incremented by one in the suffix. -For example, if security issues need addressing in the previously released version `2025.0` of Sign Requests, the new version will be labeled `2025.1`. +**Example**: If a new version of the Sign Requests endpoint is released in 2025, it will be named `2025.0`. + +Box can issue a new breaking change to API endpoints **once** per year, reserving the right to release an additional breaking change to address security or privacy concerns. In such cases, the new version will be incremented by one in the suffix. + +**Example**: If security issues need addressing in the previously released version `2025.0` of Sign Requests, the new version will be labeled `2025.1`. Each stable version is supported for a minimum of 12 months. This means that when a new version is released, the previous version becomes deprecated and will be available for use, but no new features will be added. It also means, that a new version cannot be released sooner than every 12 months. -We strongly recommend updating your apps to make requests to the latest stable API version. However, if your app uses a stable version that is no longer supported, then you will get a response with an HTTP error code `400 - Bad Request`. For details, see [Versioning Errors](#versioning-errors). +We strongly recommend updating your apps to make requests to the latest stable API version. However, if your app uses a stable version that is no longer supported, then you will get a response with an HTTP error code `400 - Bad Request`. For details, see [Versioning Errors](g://api-calls/permissions-and-errors/versioning-errors). If your request doesn't include a version, the API defaults to the initial Box API version—the version available before year-based versioning was introduced. However, relying on this behavior is not recommended when adopting deprecated -changes. To ensure consistency, always specify the API version with each request. By making your application +changes. To ensure consistency, always specify the API version, with each request. By making your application version-aware, you anchor it to a specific set of features, ensuring consistent behavior throughout the supported timeframe. +### Endpoint versioning indication + +To keep you informed about the current API state, and improve the readability of the versioned API reference, the affected endpoints are marked with a pill based on the `x-stability-level` tag or `deprecated` attribute. + +![An example of a beta pill used for API reference endpoints](./images/api-versioning-pills.png) + +| Schema element | Pill name | Description| +|---------------------|-----------|------------| +| `x-stability-level: beta` | Beta | Endpoints marked with **beta**, are offered subject to Box’s Main Beta Agreement, meaning the available capabilities may change at any time. Although beta endpoints not the same as versioned endpoints, they are a part of API lifecycle. | +|`x-stability-level: stable` or no `x-stability-level` tag | Latest version | The latest version applies to APIs that are already versioned. **Latest version** marks the most recent stable API version of an endpoint.| +| `deprecated: true` | Deprecated | An endpoint is deprecated, which means it is still available for use, but no new features are added. Such an endpoint is annotated with the `deprecated` attribute set to `true`.| + ## Calling an API version Box API versions are explicitly declared in the `box-version` header that your app makes requests to. For example: @@ -87,48 +101,18 @@ The client gets a list of all created sign requests and asks for version `2025.0 ## Versioning errors -### Calling an incorrect API version in the header - -If the API version provided in the `box-version` header is incorrect, the response will return an `HTTP 400 - Bad Request error`. -The error response will have the following structure: - -```json -{ - "type": "error", - "status": 400, - "code": "invalid_api_version", - "message": "Some error message", - "context_info": { - "conflicts": [ - "box_version value must be in the format of YYYY.MM" - ] - }, - "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors/" -} -``` - -The error message will contain information about the error and possible correct values for the `box-version` header. For example: - - - `The 'box-version' header supports only one header value per request, do not use comas.` - when the header contains multiple values separated by commas. - - `Missing required box-version header.` - when the header is missing but required. - - `Unsupported API version specified in 'box-version' header. Supported API versions: [LIST_OF_SUPPORTED_VERSIONS_COMA_SEPARATED]` - when the version specified is not supported by the API. +When using versioned API actions such as calling an incorrect API version in header or a deprecated version can lead to errors. -### Calling a deprecated API - -When a customer uses an API version that Box has marked as deprecated, the API will respond as usual. However, it will append a `Deprecation` header, stating the deprecation date, for example: - -```sh -Deprecation: date="Fri, 11 Nov 2023 23:59:59 GMT" -Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated -``` - -Customers should monitor API responses and take note when this header appears, signaling the need to plan for the transition to a new API version. +For details on possible errors, see [versioning errors](g://api-calls/permissions-and-errors/versioning-errors). ## How Box SDK versioning works -The versioning strategy is only applied to [next generation generated SDKs](https://developer.box.com/sdks-and-tools/#next-generation-sdks). +The versioning strategy applies only to [next generation generated SDKs](https://developer.box.com/sdks-and-tools/#next-generation-sdks). + Box SDKs support the **All Versions In** SDK approach. -This means that every release of SDK provides access to all endpoints in any version which is currently live. All generated SDKs use manager's approach - they group all endpoints with the same domain in one manager. For example `FolderManager` contains methods to: `create_folder`, `get_folder_by_id`, `update_folder_by_id`, `delete_folder_by_id`, `get_folder_items` and `copy_folder`.This division is done based on the value of `x-box-tag` field, which is assigned to each method in Public API Service specification. It mostly corresponds to the root of the endpoint URL, but not necessarily. For example: `FolderManager` contains methods with `https://api.box.com/2.0/folders` root URL, but the same base URL is also used in some methods of `SharedLinkFoldersManager`. +This means that every release of SDK provides access to all endpoints in any version which is currently live. All generated SDKs use manager's approach - they group all endpoints with the same domain in one manager. + +For example `FolderManager` contains methods to: `create_folder`, `get_folder_by_id`, `update_folder_by_id`, `delete_folder_by_id`, `get_folder_items` and `copy_folder`. This division is done based on the value of `x-box-tag` field, which is assigned to each method in Public API Service specification. It mostly corresponds to the root of the endpoint URL, but not necessarily. For example: `FolderManager` contains methods with `https://api.box.com/2.0/folders` root URL, but the same base URL is also used in some methods of `SharedLinkFoldersManager`. References to all managers are stored under one Box Client object. See an example of the endpoint's lifecycle: @@ -188,7 +172,7 @@ See an example of the endpoint's lifecycle: ## Breaking vs non-breaking changes -Breaking changes in the Box API occur within versioned releases, typically accompanied by a new major API version. Minor adjustments, which do not disrupt existing functionality, can be integrated into an existing API version. The following table offers illustrations of both breaking and non-breaking changes. +Breaking changes in the Box API occur within versioned releases, typically accompanied by a new major API version. Minor adjustments, which do not disrupt existing functionality, can be integrated into an existing API version. The following table lists both breaking and non-breaking changes. | API Change | Breaking change | | -------------------------------------------------------- | --------------- | @@ -211,7 +195,7 @@ Breaking changes in the Box API occur within versioned releases, typically accom -We use [oasdiff](https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md) tool to detect most of the possible breaking changes. +The [oasdiff](https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md) tool allows detecting most of the possible breaking changes. ## AI agent configuration versioning @@ -241,14 +225,14 @@ The date tells clients when this version was marked as deprecated. When building your request, consider the following: - - If you do not specify a version, the service will return the initial version—the version that existed before year-based versioning was introduced. If the initial version does not exist, the response will return an HTTP error code 400 - Bad Request. - - If the version header is specified but the requested version is unavailable, the response will return an HTTP error code 400 - Bad Request. + * If you do not specify a version, the service will return the initial version that existed before year-based versioning was introduced. If the initial version does not exist, the response will return an HTTP error code `400 - Bad Request`. + * If the version header is specified but the requested version is unavailable, the response will return an HTTP error code `400 - Bad Request`. -You can check [Versioning Errors](#versioning-errors) for more information. +For details, see [versioning errors](g://api-calls/permissions-and-errors/versioning-errors). When Box deprecates a resource or a property of a resource in the API, the change is communicated in one or more of the following ways: -- Calls that include the deprecated behavior return the response header `Box-API-Deprecated-Reason` and a link to get more information: +* Calls that include the deprecated behavior return the response header `Box-API-Deprecated-Reason` and a link to get more information: ```sh box-version: 2023.0 @@ -256,10 +240,10 @@ When Box deprecates a resource or a property of a resource in the API, the chang Box-API-Deprecated-Reason: https://developer.box.com/reference/deprecated ``` -- A notice about the deprecation is posted in the developer changelog. -- The API reference is updated to identify the affected resource and any action you need to take. -- If there is an imminent backwards-incompatible change that affects your app, then the contact email for your app might be contacted about the deprecation. +* A deprecation announcement is posted in the developer changelog. +* The API reference is updated to identify the affected resource and any action you need to take. Affected endpoints are marked with **deprecated** pill. +* If there is an imminent backwards-incompatible change that affects your app, then the contact email for your app might be contacted about the deprecation. ## Additional resources -- [API reference](https://developer.box.com/reference/) +* [API reference](https://developer.box.com/reference/) diff --git a/content/guides/api-calls/ensure-consistency.md b/content/guides/api-calls/ensure-consistency.md index 69f959d94..b3a9b130e 100644 --- a/content/guides/api-calls/ensure-consistency.md +++ b/content/guides/api-calls/ensure-consistency.md @@ -17,9 +17,9 @@ required_guides: [] alias_paths: [] --- -# Ensure Consistency +# Ensure consistency with headers -A few of the Box APIs support headers to control consistency between your +Some Box APIs support headers used to ensure consistency between your application and Box. ## `etag`, `if-match`, and `if-none-match` @@ -83,7 +83,7 @@ The following endpoints support this header. The response of these APIs calls depends on the existence of the item, and whether the `etag` value matches the most recent version. -| Item found? | Etag match? | HTTP Status | +| Item found? | Etag match? | HTTP status | | ----------- | ----------- | ----------- | | Yes | Yes | 200 | | Yes | No | 412 | diff --git a/content/guides/api-calls/images/api-versioning-pills.png b/content/guides/api-calls/images/api-versioning-pills.png new file mode 100644 index 000000000..fe0e016b5 Binary files /dev/null and b/content/guides/api-calls/images/api-versioning-pills.png differ diff --git a/content/guides/api-calls/index.md b/content/guides/api-calls/index.md index 1fff7b406..0929d9d94 100644 --- a/content/guides/api-calls/index.md +++ b/content/guides/api-calls/index.md @@ -8,7 +8,7 @@ alias_paths: # API Calls -The Box API is a restful API that attempts to follow common HTTP standards +The Box API is a restful API that follow common HTTP standards where possible. The following guides take a look at some of the useful features and common mistakes that a developer can encounter when working with these APIs. diff --git a/content/guides/api-calls/language-codes.md b/content/guides/api-calls/language-codes.md index 57daca20d..cd2c2cae5 100644 --- a/content/guides/api-calls/language-codes.md +++ b/content/guides/api-calls/language-codes.md @@ -7,10 +7,9 @@ alias_paths: - /docs/api-language-codes --- -# Language Codes +# Language codes -The Box API uses a modified version of the ISO 639-1 Language Code to specify a -user's language. +The Box API uses a modified version of the **ISO 639-1 Language Code** to specify a user's language. The following is a list of language codes used when [creating][create_user] or [updating][update_user]. diff --git a/content/guides/api-calls/permissions-and-errors/index.md b/content/guides/api-calls/permissions-and-errors/index.md index fbb0fccd0..b16ed5da7 100644 --- a/content/guides/api-calls/permissions-and-errors/index.md +++ b/content/guides/api-calls/permissions-and-errors/index.md @@ -6,7 +6,7 @@ required_guides: [] alias_paths: [] --- -# Permissions & Errors +# Permissions and errors The following guides provide information on the permissions or errors related to the Box API. It includes pages on [Common Errors][1], [Rate Limits][2], diff --git a/content/guides/api-calls/request-extra-fields.md b/content/guides/api-calls/request-extra-fields.md index c0097f0d4..4ad1e769d 100644 --- a/content/guides/api-calls/request-extra-fields.md +++ b/content/guides/api-calls/request-extra-fields.md @@ -10,25 +10,15 @@ required_guides: [] alias_paths: [] --- -# Request Extra Fields +# Request extra fields -The number of fields returned for a resource can depend on the API endpoint used +The number of fields returned for a resource depends on the API endpoint used to request the resource. -| Variant | | -| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Standard | The standard set of fields returned when requesting a resource for its own endpoints, for example when requesting a file through the [`GET /files/:id`](endpoint://get_files_id) endpoint | -| Full | The full set of fields that can be returned through a resource's own endpoints by using the `field` query parameter | -| Mini | A subset of fields that is returned when a resource is returned as a nested part of another resource, for example when a file is returned when requesting all items in a folder through the [`GET /folders/:id/items`](endpoint://get_folders_id_items) endpoint | - -The API reference documentation has each of these variations labeled in more -detail. Most notably, the file, folder, web link, and user items have full and -mini variations. - -## Using the field query parameter +## Use the `fields` query parameter To request a specific field for a resource that is not returned by default in -the standard response, append the `field` query parameter to your request. The +the standard response, append the `fields` query parameter to your request. The value of this parameter is a comma separated list of field names. ```curl @@ -48,18 +38,18 @@ curl https://api.box.com/2.0/files/12345?fields=is_package,lock \ It is important to note that when a specific field is requested no other - fields are returned except for those requested and the "base" set of fields. + fields are returned except for those requested and the **base** set of fields. For a file, this base set is comprised of the `etag`, `id`, and `type` values. -## Resource +## Resource variants -The following resource variants are available via our API. +The following resource variants are available in the Box API. ### Standard -The default set of fields returned in an API response is commonly known as the -standard resource variant. It is generally returned when requesting a resource +The default set of fields returned in an API response. +The standard variant is returned when requesting a resource through the main APIs available for that resource. For example, when requesting the [`GET /files/:id`](endpoint://get_files_id) endpoint the API will return the standard variation of a file. @@ -148,14 +138,12 @@ curl https://api.box.com/2.0/files/12345 \ ### Full -The total set of fields that can be returned in an API response is commonly known -as the full resource variant. It can generally be returned when requesting a resource +The total set of fields that can be returned in an API response. The full variant is returned when requesting a resource through the main APIs available for that resource and by appending the `fields` query parameter. For example, when requesting the [`GET /files/:id`](endpoint://get_files_id) -endpoint with the `fields=is_package,lock` parameter the API will return the fields -specified plus the basic fields for the file. +endpoint with the `fields=is_package,lock` parameter the API will return the fields specified plus the basic fields for the file. ```curl curl https://api.box.com/2.0/files/12345?fields=is_package,lock \ diff --git a/content/guides/api-calls/sorting.md b/content/guides/api-calls/sorting.md index 1ca28e177..3bf78da72 100644 --- a/content/guides/api-calls/sorting.md +++ b/content/guides/api-calls/sorting.md @@ -7,7 +7,7 @@ required_guides: [] alias_paths: [] --- -# Sorting Responses +# Sorting responses Where an API returns a collection of items it often supports sorting of API responses. diff --git a/content/guides/api-calls/status-codes.md b/content/guides/api-calls/status-codes.md index 8878837fe..27f7f3310 100644 --- a/content/guides/api-calls/status-codes.md +++ b/content/guides/api-calls/status-codes.md @@ -8,9 +8,9 @@ required_guides: [] alias_paths: [] --- -# Status Codes +# Status codes -In general, the following rules can be applied to interpret the HTTP status +The following rules can be applied to interpret the HTTP status codes received when using the Box API. | HTTP Status | | diff --git a/content/guides/api-calls/suppress-notifications.md b/content/guides/api-calls/suppress-notifications.md index 491297b72..0546008d9 100644 --- a/content/guides/api-calls/suppress-notifications.md +++ b/content/guides/api-calls/suppress-notifications.md @@ -6,9 +6,9 @@ required_guides: [] alias_paths: [] --- -# Suppress Notifications +# Suppress notifications -For some API calls, email and webhook notifications can be prevented by +For some API calls, you can block email and webhook notifications by including a `box-notifications: off` header with the API call. diff --git a/content/guides/api-calls/types-and-formats.md b/content/guides/api-calls/types-and-formats.md index fdb87e8ff..b2383e427 100644 --- a/content/guides/api-calls/types-and-formats.md +++ b/content/guides/api-calls/types-and-formats.md @@ -7,7 +7,7 @@ alias_paths: - /docs/object-model --- -# Types & Formats +# Types and formats The following sections explain some basic concepts about the types and formats that can be encountered within the Box APIs. diff --git a/content/microcopy/headers.yml b/content/microcopy/headers.yml index b6d09a544..24eef2230 100644 --- a/content/microcopy/headers.yml +++ b/content/microcopy/headers.yml @@ -235,7 +235,7 @@ secondary: // display: |- A boolean that determines whether to show the orange notification bar in the header. Must be "true" or "false" - display: "true" + display: "false" // message: |- The content of the notification