diff --git a/.cspell.json b/.cspell.json new file mode 100644 index 000000000..7c0484186 --- /dev/null +++ b/.cspell.json @@ -0,0 +1,25 @@ +{ + // Enable your dictionary by adding it to the list of `dictionaries` + "dictionaries": [ + "core-glossary" + ], + "ignoreWords": [ + "skip-list" + ], + // Tell CSpell about your dictionary + "dictionaryDefinitions": [ + { + "name": "core-glossary", + // Path to the custom word file. Relative to this `cspell.json` file. + "path": "./.style/core-glossary.txt", + // Some editor extensions will use `addWords` for adding words to your + // personal dictionary. + "addWords": true + }, + { + "name": "skip-list", //these aren't glossary words, but shouldn't be spell checked away + "path": "./.style/skip-list.txt", + "addWords": true + } + ] +} diff --git a/.spelling b/.style/.spelling similarity index 81% rename from .spelling rename to .style/.spelling index 6bd2b5962..3f3dd850d 100644 --- a/.spelling +++ b/.style/.spelling @@ -377,7 +377,7 @@ enum resource_type resource_id date_created -metafield's +metafieldʼs date_modified metafield shipping.shipperhq @@ -411,11 +411,12 @@ ReactJS Quickstart async breakpoint -Zipfile's +Zipfile +Zipfileʼs substeps spacebar prepending -test.jpg. +test.jpg jpg jpeg png @@ -439,7 +440,7 @@ viewports templating templated theming -Dont's +Donʼts SitePoint Treehouse chocolatey.org @@ -649,17 +650,17 @@ un-optimized Zurb product.html. this.page.identifier -sso +SSO params headlessly JWT sku +SKU sh1 product_id DTS ui pci - - docs/api-docs/cart-and-checkout/working-sf-apis.md postData cartItems bigcommerce.com @@ -670,14 +671,13 @@ optionId optionValues cartId deleteCartItem +GitHub itemId checkoutId lineItems lineItem - - docs/api-docs/catalog/currencies/how-currencies-work.md S-2-S https - - docs/api-docs/catalog/products-overview.md video_id SM-BLU SM-MED @@ -688,9 +688,7 @@ YELLOW-2L YELLOW-3L YELLOW-8L product_id - - docs/api-docs/customers/current-customer-api.md JWT.IO - - docs/api-docs/customers/customer-login-api.md IdP customer_login store_hash @@ -700,9 +698,7 @@ JWT.io. iss iat jti - - docs/api-docs/getting-started/about-our-api.md xml - - docs/api-docs/getting-started/authentication.md store_v2_content store_v2_content_read_only store_content_checkout @@ -710,14 +706,12 @@ store_content_checkout_read_only store_v2_customers customer_groups store_v2_customers_read_only - - docs/api-docs/getting-started/best-practices.md 60k 20k storeHash priceListId 7mil 30sec - - docs/api-docs/getting-started/building-apps-bigcommerce/building-apps.md user.id user.email owner.id @@ -727,80 +721,56 @@ owner.email auth external_install us-central1 - - docs/api-docs/getting-started/filtering.md csv not_in - - docs/api-docs/getting-started/webhooks/about-webhooks.md 3_xx_ 2_xx_ - - docs/api-docs/getting-started/webhooks/setting-up-webhooks.md index.js. Res.send res.send http - - docs/api-docs/getting-started/webhooks/webhook-events.md statusUpdated sku couponApplied lineItem cartId - - docs/api-docs/partner/app-store-approval-requirements.md 130px 200x200px 200px 158px - - docs/api-docs/partner/becoming-a-partner.md 15-day - - docs/api-docs/getting-started/api-status-codes.md 2xx 3xx 4xx 5xx - - docs/api-docs/payments/payments-api-overview.md vnd.bc.v1 - - docs/api-docs/store-management/shipping/shipping-provider-api.md 70x70 - - docs/stencil-docs/configure-store-design-ui/defining-global-styles.md http _color.scss - - docs/stencil-docs/configure-store-design-ui/store-design-overview.md -schema.json. +schema.json 100x250 175x275 300x300 - - docs/stencil-docs/deploying-a-theme/checking-a-themes-size.md img - - docs/stencil-docs/developing-further/google-amp.md css - - docs/stencil-docs/developing-further/stored-credit-card-management.md pre-2 - - docs/stencil-docs/getting-started/about-stencil.md -6.x. - - docs/stencil-docs/installing-stencil-cli/installing-stencil.md +6.x 2.7.x - - docs/stencil-docs/installing-stencil-cli/live-previewing-a-theme.md pre - - docs/stencil-docs/installing-stencil-cli/troubleshooting-your-setup.md TR-300 Node.js. bitbucket - - docs/stencil-docs/javascript-and-event-hooks/dynamic-content-rendering.md Utting - - docs/stencil-docs/javascript-and-event-hooks/npm-tutorials.md Foundation-datepicker - - docs/stencil-docs/localization/translation-keys.md rw-r - - docs/stencil-docs/reference-docs/common-objects.md x21B3 sku url - - docs/stencil-docs/reference-docs/global-objects-and-properties.md Is_Ajax cart_id shippingaddressform editaccount rss - - docs/stencil-docs/reference-docs/handlebars-helpers-reference.md withBefore withAfter withLast @@ -811,14 +781,12 @@ cdn customcdn _or_ dot.cases - - docs/stencil-docs/reference-docs/other-objects-and-properties-overview.md chooseprefix class_name private_id singleline singleselect expires_at - - docs/stencil-docs/reference-docs/stencil-utils-api-reference.md Utils utils getPage @@ -829,9 +797,7 @@ itemRemove itemId params configureCart - - docs/stencil-docs/storefront-customization/custom-templates.md abcdefghijklmnop brandname 252d - - docs/stencil-docs/storefront-customization/using-disqus.md product.id diff --git a/.style/core-glossary.txt b/.style/core-glossary.txt new file mode 100644 index 000000000..5777e6ed2 --- /dev/null +++ b/.style/core-glossary.txt @@ -0,0 +1,77 @@ + +BigCommerce +bigcommerce +bodl +BODL +upsert +!above +!access +!allows +!dev key +!developer key ++application +!back-end +!front-end +!backwards compatible +!below +!blacklist +!whitelist +allowlist +denylist +!check +!click on +![here] +![click here] +!id +ID +!comprise +!cons +!console +!content type +media type +!curated roles +!cleansing +!data set +!datasource +!data store +!datatype +!deep-link* +!deselect +!desire +!dialogue +!doc +!docs +!article +!topic +!dropdown +!dummy +!easy +!easily +!e.g. +!eg +!tag +!e-mail +!end point +!file name +!filesystem +!flag +!functionality +!he +!him +!his +!she +!her +!hers +!hamburger +!hit +!hover +!host name +!i.e. +!ie +!impactful +!ingest +!in order to +!just + +via +will diff --git a/.style/skip-list.txt b/.style/skip-list.txt new file mode 100644 index 000000000..98ea16756 --- /dev/null +++ b/.style/skip-list.txt @@ -0,0 +1 @@ +usleep diff --git a/docs/api-docs/apps/guide/apps-11-best-practices.mdx b/docs/api-docs/apps/guide/apps-11-best-practices.mdx index ebe796fd1..40b34449e 100644 --- a/docs/api-docs/apps/guide/apps-11-best-practices.mdx +++ b/docs/api-docs/apps/guide/apps-11-best-practices.mdx @@ -25,71 +25,7 @@ For details, see [Security Considerations in RC6749](https://tools.ietf.org/html ## API requests -### Use the latest APIs - -BigCommerce is actively developing V3 API endpoints. By using the newest endpoints, you will ensure that your app has access to the latest resources. You will also be better positioned to provide a user experience consistent with what merchants will see in their BigCommerce store's control panel. To stay up to date, bookmark our [changelog](/changelog). - -### Plan for API updates - -We encourage developers to write code against our API that will not break if an endpoint starts returning additional fields, as these "non-breaking" changes may be made by us without warning as part of our normal development. Breaking changes will be made with early warning, typically via our developer [changelog](/changelog) and other channels as appropriate. For beta APIs and in exceptional cases where we know using a particular endpoint to be zero, we may make breaking changes without warning. - -### Thread API requests - -Thread requests to make rapid updates via API. Threaded requests allow you to send multiple requests at a time. They can come from a different open connection or multiple requests to the same resource. Our [Ruby API client](https://github.com/bigcommerce/bigcommerce-api-ruby) is thread-safe; it satisfies the need for multiple threads to access the same shared data and the need for a shared piece of data to be accessed by only one thread at a time. These attributes can reduce the total time that your app will require to complete a series of requests. - -### Respect API rate limits - -BigCommerce rate limits all API requests made to a store in a thirty-second window. The rate limit varies by plan level. - -| Plan | Requests per Hour | Requests per 30 Seconds | -| ------------------------ | ----------------- | --------------------------- | -| Enterprise | - | Unlimited\* | -| Enterprise Sandboxes | - | Unlimited\* | -| Pro | `60,000` | `450` | -| Plus | `20,000` | `150` | -| Standard | `20,000` | `150` | -| Non-Enterprise Sandboxes | `20,000` | `150` | - - - \* The **Unlimited** rate limit on BigCommerce Enterprise plans means that stores on this plan will not be artificially rate-limited on the basis of API-requests-per-unit-of-time. However, there are physical limits to the infrastructure which may limit the maximum throughput of requests on any given API endpoint. BigCommerce also reserves the right to limit unreasonable or abusive API activity in the interest of platform stability, per our [Terms of Service](https://www.bigcommerce.com/terms/api-terms/). - - -Apps making API requests to a store share the store's rate limit. This promotes fairness between apps accessing the API simultaneously, and prevents a single app from consuming the store's entire limit. - -BigCommerce allots applications a share of a store's rate limit via quota system, and exposes rate limit positioning to applications using the following response headers. - -```http filename="Example: Rate limit headers" -X-Rate-Limit-Requests-Left: 6 -X-Rate-Limit-Requests-Quota: 25 -X-Rate-Limit-Time-Reset-Ms: 3000 -X-Rate-Limit-Time-Window-Ms: 5000 -``` - -| Name | Description | -| -- | -- | -| `X-Rate-Limit-Time-Window-Ms` | size of rate limit window in milliseconds | -| `X-Rate-Limit-Time-Reset-Ms` | time remaining in window in milliseconds | -| `X-Rate-Limit-Requests-Quota` | total requests allotted to your application per window | -| `X-Rate-Limit-Requests-Left` | remaining requests allotted to your application in current window | - -BigCommerce responds to apps that exceed the quota with a [429](/api-docs/getting-started/api-status-codes#4xx-client-error) response. When this happens, applications should pause requests until the number of milliseconds in `X-Rate-Limit-Time-Reset-Ms` elapses. - -### Play nicely when making parallel requests - -BigCommerce's REST endpoints accept requests made in parallel. Applications making parallel requests should monitor rate limit headers to avoid a `429` response. Methods for doing so include the following: -* Slow rate of requests when `X-Rate-Limit-Requests-Left` nears zero. -* Self-throttles requests to the average rate of `(X-Rate-Limit-Requests-Quota / X-Rate-Limit-Time-Window-Seconds)`. - - - Endpoints that accept bulk requests may have specific limitations on the number of accepted parallel requests. For example, making multiple parallel `upsert` requests to `/pricelists/{price_list_id}/records` will result in a `429` error response. These limitations are documented at the operation level in the API Reference. - - - -### Respect platform limits - -To promote stability and performance, BigCommerce sets store maximums on certain entities and values, and responds to API requests that would exceed them with a `403 Forbidden` response. - -For a list of limits, see [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) in the Help Center. +For recommendations on API request-related best practices, including rate limits, threading, parallel requests, and the finer points of request headers, see our article on [Best Practices](/api-docs/getting-started/best-practices). ## Webhook events @@ -123,6 +59,20 @@ Bigcommerce.init({ - If your app requires the user to sign in at launch, use the information BigCommerce sends to your callback URL to authenticate the user without asking for a username and password each time. - If you plan to share user testimonials, add a link to your full case study in the case studies field. + +### Offer multi-user access + +Merchants often have more than one person who can access a store's control panel. BigCommerce allows additional users to access an app when the store owner has granted them appropriate permissions. The requirements for supporting multi-user app access are: +* The app must save the API account access token for each store with its `store_hash`, rather than a user's info. +* In the app's [Developer Portal profile](https://devtools.bigcommerce.com), you must [enable multiple users](/api-docs/apps/guide/developer-portal#edit-technical-details). + +In the payload returned when a user launches an app, users are distinguished by `owner_email` versus `user_email`. If these two emails match, the user is the store owner. + +Enabling user removal is optional. If you want merchants to be able to remove users, you can do so by writing a `remove_user` callback and [adding its URL](/api-docs/apps/guide/developer-portal#edit-technical-details) to your app's [Developer Portal profile](https://devtools.bigcommerce.com). For more advanced implementations, you can enable the store owner to grant specific permissions to different non-admin users. For example, `person1@example.com` could be permitted to edit product inventory but not view orders. If you decide to implement user permissions in your app, it’s a great feature to advertise. + +For more information, see [Multi-User Support](/api-docs/apps/guide/intro#multi-user-support). + + ## Deployment ### Consider hosting on Google Cloud Platform's us-central1 region diff --git a/docs/api-docs/getting-started/about-our-api.mdx b/docs/api-docs/getting-started/about-our-api.mdx index 4bf15c460..e1ec15664 100644 --- a/docs/api-docs/getting-started/about-our-api.mdx +++ b/docs/api-docs/getting-started/about-our-api.mdx @@ -12,9 +12,11 @@ If you're new to building BigCommerce apps, we recommend that you start by explo When you're ready to play with our APIs, check out the [API Request Quick Start](/api-docs/getting-started/making-requests). ## Available APIs + BigCommerce has several APIs that let you manage store data, authenticate customers, make client-side queries for product information, and more. ### REST Store Management APIs + BigCommerce's Store Management and Payment APIs (for example, the [Catalog API](/docs/rest-catalog)) allow you to manage transactions, modify store data, and act as store administrator. Example use cases include the following: * Add and update products in a store * Update a customer's order and change the order status @@ -22,7 +24,8 @@ BigCommerce's Store Management and Payment APIs (for example, the [Catalog API]( * Manage a customer's store account details ### REST Storefront API -The [REST Storefront API](/docs/rest-storefront/carts) allows you to manage customer carts, checkouts, and order information client-side. Example use cases include the following: + +The [REST Storefront API](/docs/rest-storefront/carts) lets you manage customer carts, checkouts, and order information client-side. Example use cases include the following: * Add an item with JavaScript to a shopper's cart from a Stencil storefront * Programmatically retrieve and display information to a customer about their recent order * Update the billing address of a checkout @@ -30,13 +33,15 @@ The [REST Storefront API](/docs/rest-storefront/carts) allows you to manage cust ### GraphQL Storefront API -BigCommerce's [GraphQL Storefront API](/docs/graphql-storefront) allows you to query and mutate products, customers, and carts, then launch a checkout on a headless storefront as well as from a native storefront's frontend. Example use cases include the following: + +BigCommerce's [GraphQL Storefront API](/docs/graphql-storefront) lets you query and mutate products, customers, and carts, then launch a checkout on a headless storefront as well as from a native storefront's frontend. Example use cases include the following: * Add additional product data to a Stencil storefront * Access customer data on the frontend of a site * Manage shopper's carts on a headless storefront * Fetch category and brand details from a store's frontend ### Customer Login API + The [Customer Login API](/api-docs/storefront/customer-login-api) lets you programmatically sign customers in to a BigCommerce storefront. Example use cases include the following: * Sign customers in to a BigCommerce store from a third-party account or a headless storefront * Enable login using credentials other than email and password, such as a phone number @@ -44,7 +49,8 @@ The [Customer Login API](/api-docs/storefront/customer-login-api) lets you progr ### Current Customer API -BigCommerce's [Current Customer API](/api-docs/customers/current-customer-api) allows you to determine which customer is logged in to a storefront during a session. + +BigCommerce's [Current Customer API](/api-docs/customers/current-customer-api) lets you determine which customer is logged in to a storefront during a session. * Confirm a customer's identity in the browser * Validate a customer's identity to display specific information to them from an external app @@ -53,15 +59,21 @@ BigCommerce's [Current Customer API](/api-docs/customers/current-customer-api) a Make BigCommerce API requests in the context of the **storefront**, BigCommerce **API server**, or **app server**. Each of the following APIs listings links to its section of our [Authentication and Example Requests](/api-docs/getting-started/authentication) article, which contains the base URL of the API in question. -| Authentication and Example Requests | Context | -|:------------------------------------|:--------| -| [REST Store Management APIs](/api-docs/getting-started/authentication#access-tokens) | API server | -| [REST Storefront API](/api-docs/getting-started/authentication#same-origin-cors-authentication) | storefront | +| API or Use Case | Context | +|:----------------|:--------| +| [GraphQL Account API](/api-docs/getting-started/authentication#access-tokens), including [Users](/docs/graphql-users/overview) | server | +| [GraphQL Admin API](/api-docs/getting-started/) | server | | [GraphQL Storefront API](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) | storefront | +| [REST Store Management APIs](/api-docs/getting-started/authentication#access-tokens) | server | +| [REST Storefront API](/api-docs/getting-started/authentication#same-origin-cors-authentication) | storefront | | [Customer Login API](/api-docs/getting-started/authentication#user-generated-jwts) | storefront | | [Current Customer API](/api-docs/getting-started/authentication#client-id) | storefront | -| [Payments API](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) | API server | -| [Apps that host REST Provider APIs (provider apps)](/api-docs/getting-started/authentication#developer-configured-authentication) | app server | +| [Payments API](/api-docs/getting-started/authentication#bigcommerce-generated-jwts) | server | +| [Apps that host REST Provider APIs (provider apps)](/api-docs/getting-started/authentication#developer-configured-authentication) | server | +| Apps hosted in the store control panel (single-click apps) | server | +| Single-store frontend scripts | storefront | +| Headless storefronts with backend or request proxy | server | +| Serverless headless storefronts | storefront, GraphQL-only | ## Available store resources @@ -69,7 +81,7 @@ Make BigCommerce API requests in the context of the **storefront**, BigCommerce | Resource | Description | |:---------|:------------| | [Catalog](/docs/rest-catalog) | The Catalog API manages products, brands, and categories for a store. | -| [Store Infomation](/docs/rest-management/store-information) | Get system timestamp and basic store information. | +| [Store Information](/docs/rest-management/store-information) | Get system timestamp and basic store information. | | [Currency](/docs/rest-management/currencies) | Manage currency displayed on the storefront. | | [Geography](/docs/rest-management/geography) | Get a list of states and countries. | | [Tax Class](/docs/rest-management/tax-classes) | Manage tax classes available on a store. | @@ -109,22 +121,31 @@ A media type is the format of the request or response body. BigCommerce APIs acc ### Requests -#### Request headers +For more information about required request headers, consult the [API reference](/docs/api) for the endpoint or graph you want to use. -Store Management and Payments API requests require the `Accept`, `X-Auth-Token`, and `Content-Type` headers. +#### Standard request headers -| Header | Allowed Values | Description | Example | +| Header | Expected value or type | Description | Example | |:-------|:---------------|:------------|:--------| -| `Accept` | `application/json` (for .json requests) `application/xml` (for .xml requests) | The MIME type format for receiving a response.|`application/xml` | -| `Content-Type` | `application/json` (for JSON requests) `application/xml` (for XML requests) | The MIME type of the request body. Used to validate and parse the request to the API. | `application/json` | -| `User-Agent` | String | While it is not required, we ask that you specify a user agent which identifies your integration/client with your requests. | -| `X-Auth-Token` | String | Access token authorizing the app to access resources on behalf of a user. | +| `Accept` | MIME types | The MIME type format that indicates which response type the request expects. For more information, see [HTTP Docs: Accept Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept). | `application/json` | +| `Content-Type` | MIME types | The MIME type of the request body. The API uses this value to validate and parse the request. For more information, see [HTTP Docs: Content-Type Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type). | `application/json` | +| `User-Agent` | String | We ask that you specify a user agent to identify your integration or client. | `PostmanRuntime/7.32.3` | +| `Authorization` | String | Requests to the [Process payments](/docs/rest-payments/processing) endpoint and the [GraphQL Storefront API](/docs/graphql-storefront) use the `Authorization` header to authenticate. For more information, see [HTTP Docs: Authorization Header (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization). | `Bearer {{storefront_token}}` or `PAT {{payment_access_token}}` | + +#### BigCommerce-specific request headers + +| Header | Expected value or type | Description | +|:-------|:-----------------------|:------------| +| `X-Auth-Token` | API account access token | Requests to the REST Management, Catalog, GraphQL Admin, and GraphQL Account APIs use this header to authenticate. Some Payment endpoints also use this header. | +| `X-Auth-Client` | API account client ID | No longer required for any requests to BigCommerce. | | `X-Correlation-Id` | UUID in an 8-4-4-4-12 format | An identifier unique to a set of related requests. For use on headless storefronts, excluding BigCommerce for WordPress. For more information, see [Best Practices](/api-docs/getting-started/best-practices#correlating-requests) or the [Headless Guide](/api-docs/storefronts/guide/overview#correlating-requests). | #### Request content type + When performing a request that contains a body, specify the type of content you are sending with the `Content-Type` header. This typically applies to `PUT` and `POST` requests. #### Request structure + The body of a JSON request is an object containing a set of key-value pairs. A simple representation of a product object is: ```json filename="Example request body: Product object" showLineNumbers copy @@ -141,6 +162,7 @@ The body of a JSON request is an object containing a set of key-value pairs. A s HTTP response header names are case-insensitive; see the [HTTP specification on field names](https://www.rfc-editor.org/rfc/rfc9110.html#name-field-names) for more information. For example, your application may receive `x-rate-limit-requests-left` rather than `X-Rate-Limit-Requests-Left`, so plan your implementation accordingly. Most open source HTTP clients treat headers with the appropriate case insensitivity. +#### Standard response headers | Header | Possible Values | Description | Example | |:-------|:----------------|:------------|:--------| @@ -149,17 +171,27 @@ HTTP response header names are case-insensitive; see the [HTTP specification on | `Content-Type` | `application/json` | The MIME type of the response, dependent on the extension of the endpoint that was requested. | `application/json` | | `Content-Location` | A URI | Sent if the request was redirected. | `/api/v2/orders/5.json` | | `Location` | A URI | The URI of a newly created resource. Sent with a `201 Created` response. | `/api/v2/products/7` | +| `Content-Encoding` | `gzip` | Allows API clients to request content to be compressed before being sent back in the response to an API request. | `gzip` | +| `Transfer-Encoding` | `chunked` | Specifies the form of encoding used to transfer the resource. | `chunked` | + +{/* | `Strict-Transport-Security` | | | | */} + +#### BigCommerce-specific response headers + +| Header | Possible Values | Description | Example | +|:-------|:----------------|:------------|:--------| +| `X-Rate-Limit-Time-Window-Ms` | number | Shows the size of your current rate-limiting window, in milliseconds. | `30000` | +| `X-Rate-Limit-Time-Reset-Ms` | number | Shows how many milliseconds are remaining in the window. In this case, 15000 milliseconds – so, 15000 milliseconds after this request, the API quota will be refreshed. |`15000 `| +| `X-Rate-Limit-Requests-Quota` | number | Shows how many API requests are allowed in the current window for your client. | `150` | +| `X-Rate-Limit-Requests-Left` | number | Details how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 35 more requests in the next 15000 milliseconds; on the 36th request within 15000 milliseconds, you would be rate-limited and receive an HTTP 429 response. | `35` | | `X-Retry-After` | integer | Rate limited response, indicating the number of seconds before the quota refreshes. See [Rate Limits](/api-docs/getting-started/best-practices#api-rate-limits) for more information. | `15` | -| `X-BC-ApiLimit-Remaining` | integer | The number of API requests remaining for the current period (rolling one hour). See [Rate Limits](/api-docs/getting-started/best-practices#api-rate-limits) for more information. | `987` | +| `X-BC-ApiLimit-Remaining` | integer | The number of API requests remaining for the current period (rolling one hour). | `987` | | `X-BC-Store-Version` | A version number | The version of BigCommerce on which the store is running. This header is available on versions 7.3.6+. | ` 7.3.6` | -| `Content-Encoding` | `gzip` | Allows API clients to request content to be compressed before being sent back in the response to an API request. | `gzip` | -| `Transfer-Encoding` | `chunked` | Specifies the form of encoding used to transfer the resource. | `chunked` -| `X-Rate-Limit-Requests-Left` | number | Details how many remaining requests your client can make in the current window before being rate-limited. In this case, you would expect to be able to make 6 more requests in the next 3000 milliseconds; on the 7th request within 3000 milliseconds, you would be rate-limited and would receive an HTTP 429 response. | `16101491` | -| `X-Rate-Limit-Requests-Quota` | number | Shows how many API requests are allowed in the current window for your client. | `16101495` | -| `X-Rate-Limit-Time-Reset-Ms` | number | Shows how many milliseconds are remaining in the window. In this case, 3000 milliseconds – so, 3000 milliseconds after this request, the API quota will be refreshed. |`30000 `| -| `X-Rate-Limit-Time-Window-Ms` | number | Shows the size of your current rate-limiting window. | `9762` | + +{/* | `X-Request-ID` | | | | */} #### Response content type + When requesting a resource that returns a body, specify the type of content you want to receive with the `Accept` header. Alternatively, you can supply an extension to the resource you're requesting. The priorities with which you can process these methods are: @@ -167,6 +199,7 @@ The priorities with which you can process these methods are: * Accept header low priority types (priorities less than 1, e.g. `Accept: application/json;q=0.9`) ### Request Structure + The body of a JSON request is an object containing a set of key-value pairs. A simple representation of a product object is: ```http filename="Example JSON request body" showLineNumbers copy @@ -178,13 +211,13 @@ The body of a JSON request is an object containing a set of key-value pairs. A s ``` ### Response structure + Responses are structured similarly to requests. If a request returns a single object, then the response will contain a single object containing the fields for that resource. ```http filename="Example request: Get a category" GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories/{{category_id}} ``` - ```json filename="Example response: Get a category" showLineNumbers copy { "data": { @@ -216,12 +249,15 @@ GET https://api.bigcommerce.com/stores/{{store_hash}}/v3/catalog/categories/{{ca ## Support ### Developer community -The [developer community](https://support.bigcommerce.com/s/group/0F913000000HLjECAW/bigcommerce-developers) is a great place to get help from other developers who work on the BigCommerce platform. If you have BigCommerce-specific questions, this online forum is the best place to ask. It's also an excellent place for beginners to get assistance. + +The [developer community](/community) is a great place to get help from other developers who work on the BigCommerce platform. If you have BigCommerce-specific questions, this online forum is the best place to ask. It's also an excellent place for beginners to get assistance. ### BigCommerce at Stack Overflow -Are you a more experienced developer or have a programming language-specific question? [StackOverflow](https://stackoverflow.com/questions/tagged/bigcommerce) is a good place to ask questions and get help. The developer community is the best place to get answers about the BigCommerce platform. + +Are you a more experienced developer or have a programming language-specific question? [Stack Overflow](https://stackoverflow.com/questions/tagged/bigcommerce) is a good place to ask questions and get help. The developer community is the best place to get answers about the BigCommerce platform. ## Resources -* [Developer Community](https://support.bigcommerce.com/s/group/0F913000000HLjECAW/bigcommerce-developers) + +* [Developer Community](/community) * [Terms of Service](https://www.bigcommerce.com/terms/api-terms/) -* [StackOverflow](https://stackoverflow.com/questions/tagged/bigcommerce) +* [BigCommerce on Stack Overflow](https://stackoverflow.com/questions/tagged/bigcommerce) diff --git a/docs/api-docs/getting-started/authentication.mdx b/docs/api-docs/getting-started/authentication.mdx index 7a6b9719c..2cd0ccd6e 100644 --- a/docs/api-docs/getting-started/authentication.mdx +++ b/docs/api-docs/getting-started/authentication.mdx @@ -129,7 +129,7 @@ The following table lists the APIs that authenticate with a client ID. For OAuth ## Dynamic tokens -Several of our APIs authenticate with JSON web tokens, or _JWTs_. JWTs authorize both the requester and the recipient because they contain a signed payload that the recipient must successfully decrypt before working with the transmitted data. Some JWTs can be used unlimited times within an expiration window; others must be unique to each request. +Several of our APIs authenticate with JSON web tokens, or _JWTs_. JWTs authorize both the requester and the recipient because they contain a signed payload that the recipient must successfully decrypt before working with the transmitted data. You can use some JWTs for any number of requests within an expiration window; others must be unique to each request. Our JWT-based authentication schemes fall into the following categories: * The user passes a [BigCommerce-generated JWT](#bigcommerce-generated-jwts) as part of the value of the `Authorization` header @@ -156,7 +156,7 @@ The following table lists the APIs that use the `Authorization` header, along wi | API description | Obtain a JWT | Endpoint reference | API account type | Authorization header value | |:----------------|:-------------|:-------------------|:-----------------|:---------------------------| | [GraphQL Storefront API](/api-docs/storefront/graphql/graphql-storefront-api-overview) | [Create a token](/docs/storefront-auth/tokens#create-a-token), Stencil context | [Create a Storefront query](/docs/graphql-storefront) | store | `Bearer {{TOKEN}}` | -| [Payments API](/api-docs/store-management/payments-api-overview) | [Create a payment access token](/docs/rest-payments/tokens#create-payment-access-token), `completeCheckout` with the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout#handling-payments) | [Process a payment](/docs/rest-payments/processing#process-payment) | app or store | `PAT {{TOKEN}}` | +| [Payment processing](/api-docs/store-management/payments-api-overview) endpoint | [Create a payment access token](/docs/rest-payments/tokens#create-payment-access-token), `completeCheckout` with the [GraphQL Storefront API](/api-docs/storefront/graphql/carts-and-checkout#handling-payments) | [Process a payment](/docs/rest-payments/processing#process-payment) | app or store | `PAT {{TOKEN}}` | To obtain a dynamic token, send a request to the REST endpoint listed in the **Obtain a JWT** column or consult the article listed in the **API Description** column. Use an API account with the appropriate [token creation OAuth scopes](/api-docs/getting-started/api-accounts#token-creation-scopes). @@ -263,6 +263,7 @@ The following table lists the APIs that rely on user-generated JWTs. For OAuth s | [Customer Login API](/api-docs/storefront/customer-login-api) | See API description | [SSO API Reference](/docs/storefront-auth/customer-login) | app | ### Customer Login API example request + For the Customer Login API, your request will look something like the following: ```js filename="Example GET request: Customer Login API" diff --git a/docs/api-docs/getting-started/best-practices.mdx b/docs/api-docs/getting-started/best-practices.mdx index 1af2aa496..aff1691a5 100644 --- a/docs/api-docs/getting-started/best-practices.mdx +++ b/docs/api-docs/getting-started/best-practices.mdx @@ -5,15 +5,15 @@ keywords: rate limits, best practices, # API Best Practices -## Keep your integration up-to-date +## Keep your integration up to date -BigCommerce frequently enhances its core product and is actively developing v3 API endpoints. By using the newest API version, you will ensure that your app has access to the latest resources. You will also be better positioned to provide a user experience consistent with what merchants see in their BigCommerce store’s control panel. To stay up to date, bookmark our [changelog](/changelog). +BigCommerce frequently enhances its core product and is actively enhancing REST endpoints, as well as expanding the graphs accessible to our growing family of GraphQL APIs. Using the latest information lets you update your app to take advantage of the most current resources. You also position your app or implementation to provide a user experience consistent with what merchants see in their BigCommerce store control panel. To stay up to date, bookmark our [changelog](/changelog). ## Anticipate changes to BigCommerce APIs At BigCommerce, we make a distinction between "breaking" and "non-breaking" changes. -In most cases, we will give advance notice in our developer [changelog](/changelog) when we make any of the following "breaking" changes. However, we will make breaking changes _without warning_ to non-production (alpha/beta) endpoints, or when analytics indicate that an endpoint has no traffic. +In most cases, we will give advance notice in our developer [changelog](/changelog) when we make any of the following "breaking" changes. However, we will make breaking changes _without warning_ to alpha and beta endpoints and graph nodes, or when analytics indicate that an endpoint has no traffic for three months. Examples of breaking changes include: @@ -34,62 +34,43 @@ Examples of non-breaking changes include: We encourage you to write robust, resilient code that will not break or leak memory if an endpoint begins to return additional fields. ## Use webhooks to listen for changes -To keep data in your application up-to-date, [webhooks](/api-docs/getting-started/webhooks/about-webhooks) provide a great alternative to periodic API polling. Use an [OAuth API account](/api-docs/getting-started/api-accounts) to register and subscribe to webhook-enabled events relevant to your application. + +To keep your app's data up to date, [webhooks](/api-docs/getting-started/webhooks/about-webhooks) provide a great alternative to periodic API polling. Use a [store-level or app-level API account](/api-docs/getting-started/api-accounts) to register and subscribe to webhook-enabled events relevant to your app. When an event your app is listening for occurs, BigCommerce sends a payload with a few identifying details relevant to the event. See a list of [webhook events and their payloads](/api-docs/store-management/webhooks/webhook-events). Use the payload data points to make subsequent API requests for more details. ### Avoid polling the Storefront Cart API -Client-side applications should avoid polling the [Storefront Cart API](/api-reference/cart-checkout/storefront-cart-api) on interval. Thousands of browsers could poll the Storefront Cart API at any given time, causing a significant load increase to BigCommerce's servers. We may take action against a store using this practice to prevent service interruptions to other stores. -Consider writing a server-side application to subscribe to the [Cart Webhook](/api-docs/store-management/webhooks/webhook-events#carts) as an alternative to polling the Storefront Cart API, and only query the Storefront Cart API as a response to user input. Storing cart information in the browser cache is an alternative method for keeping cart information up to date across browser tabs. +Client-side applications should avoid polling the [REST Storefront Cart API](/docs/rest-storefront/carts) on interval. Millions of browsers could poll this API at any given time, causing a significant load increase to BigCommerce's servers. We may take action against a store using this practice to prevent service interruptions to other stores. + +As an alternative, consider using a server-side app to subscribe to [cart webhook events](/api-docs/store-management/webhooks/webhook-events#carts), then query the Storefront Cart API only as a response to user input. Storing cart information in the browser cache is an alternative method for updating cart information across browser tabs. You may also be interested in the [growing list of events](/api-docs/partner/analytics-solutions/bodl#bodl-event-schemas) available to native storefronts with our Open Data Layer enabled. ## Thread API requests You can use threaded requests in order to quickly update information in an API. Threaded requests allow you to send multiple requests at one time. They can come from a different open connection or multiple requests to the same resource. -The [BigCommerce Ruby API](https://github.com/bigcommerce/bigcommerce-api-ruby) client is thread-safe. It satisfies the need for multiple threads to access the same shared data and the need for only one thread to access a shared piece of data at any given time. These attributes can reduce the total time that your app will require to complete a series of requests. - -## Marketplace apps - -### Offer multi-user access - -Merchants often have more than one person who can access a store's control panel. BigCommerce allows additional users to access an app when the store owner has granted them appropriate permissions. The requirements for supporting multi-user app access are: -* The app must save the API account access token for each store with its `store_hash`, rather than a user's info. -* In the app's [Developer Portal profile](https://devtools.bigcommerce.com), you must [enable multiple users](/api-docs/apps/guide/developer-portal#edit-technical-details). - -In the payload returned when a user launches an app, users are distinguished by `owner_email` versus `user_email`. If these two emails match, the user is the store owner. - -Enabling user removal is optional. If you want merchants to be able to remove users, you can do so by writing a `remove_user` callback and [adding its URL](/api-docs/apps/guide/developer-portal#edit-technical-details) to your app's [Developer Portal profile](https://devtools.bigcommerce.com). For more advanced implementations, you can enable the store owner to grant specific permissions to different non-admin users. For example, `person1@example.com` could have permission to edit product inventory but not to view orders. If you decide to implement user permissions in your app, it’s a great feature to advertise. - -For more information, see [Multi-User Support](/api-docs/apps/guide/intro#multi-user-support). +The [BigCommerce Ruby API client](https://github.com/bigcommerce/bigcommerce-api-ruby) is thread-safe. It satisfies both the need for multiple threads to access the same shared data and the need for only one thread to access a shared piece of data at any given time. This design pattern can reduce the total time that your app requires to complete a series of requests. ## API rate limits -Apps that authenticate with OAuth are rate-limited based on a quota that is refreshed every few seconds. The maximum quota for a store will vary depending on the [store’s plan](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits). -| Plans & sandboxes | Maximum quota | -|:------------------|:--------------| -| Enterprise plans and Enterprise sandboxes (Enterprise-Test) | Unlimited\*| +Apps that authenticate with OAuth are rate-limited based on a quota that is refreshed every few seconds. The maximum quota for a store will vary depending on the store plan and resources requested. + +| Plans & sandboxes | Quotas | +|:------------------|:-------| +| Enterprise plans and Enterprise sandboxes (Enterprise-Test) | by plan\* and [resource](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits) | +| All other sandboxes (Dev/Partner/Employee) | by [resource](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits) | | Pro plans| 60k per hour (450 / 30sec) | -| All other sandboxes (Dev/Partner/Employee) | Unlimited\*| -| Plus & Standard plans| 20k per hour (150 / 30sec) | +| Plus & Standard plans| 20k per hour (150 / 30sec) | - - The **Unlimited** rate limit on BigCommerce Enterprise plans means that stores on this plan will not be artificially rate-limited on the basis of API requests per unit of time. However, there are physical limits to the infrastructure which may limit the maximum throughput of requests on any given API endpoint. BigCommerce also reserves the right to limit unreasonable or abusive API activity in the interest of platform stability, per our [Terms of Service](https://www.bigcommerce.com/terms/api-terms/). + + \* The **Unlimited** rate plan for select BigCommerce Enterprise clients means that these stores are not rate limited by number of requests per unit of time. However, there are physical infrastructure-related constraints that may limit the maximum throughput of requests for a given resource. For more on resource constraints, consult our article on [object-related limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits). + + BigCommerce reserves the right to limit unreasonable or abusive API activity in the interest of platform stability, per our [Terms of Service](https://www.bigcommerce.com/terms/api-terms/). - Each request to the API consumes one available request from the quota. When an app hits the quota limit, subsequent requests are rejected until the quota is refreshed. -The store’s overall quota is distributed across all apps that are accessing the store at a given time. This provides fairness for multiple apps that are accessing the API simultaneously, preventing a single app from consuming the store’s entire quota by itself. The quota might adjust as additional clients connect or disconnect while you’re running requests. - -### Concurrent API call rate limits - -Certain BigCommerce API resources rate-limit concurrent requests. This is to ensure the performance and reliability of the platform for all of our users. API calls are metered on a per-store, per-endpoint basis. These limitations are subject to change. - -| Limit | Endpoint | Method | -|:------|:---------|:-------| -| 10 | `/stores/:hash/v3/customers` | `POST` | - +A store’s overall quota is distributed across all apps that are accessing that store at a given time. This prevents a single app from consuming the store’s entire quota by itself. The quota available to a single app adjusts as additional clients start and stop making requests. ### Playing nicely with the platform @@ -99,69 +80,77 @@ Certain BigCommerce API resources rate-limit concurrent requests. This is to ens Every API response’s HTTP headers give you full visibility into your position in the rate-limiting algorithm: -```http filename="Example: Rate limit headers" -X-Rate-Limit-Requests-Left: 6 -X-Rate-Limit-Requests-Quota: 25 -X-Rate-Limit-Time-Reset-Ms: 3000 -X-Rate-Limit-Time-Window-Ms: 5000 +```http filename="Standard plan example: Rate limit headers" +X-Rate-Limit-Time-Window-Ms: 30000 +X-Rate-Limit-Time-Reset-Ms: 15000 +X-Rate-Limit-Requests-Quota: 150 +X-Rate-Limit-Requests-Left: 35 ``` -| Name | Description | -|:-----|:------------| -| `X-Rate-Limit-Time-Window-Ms`| Shows the size of your current rate limiting window. In this case, it’s 5000 milliseconds.| -| `X-Rate-Limit-Time-Reset-Ms` | Shows how many milliseconds are remaining in the window. In this case, 3000 milliseconds. 3000 milliseconds after this request, the API quota will be refreshed. | -| `X-Rate-Limit-Requests-Quota` | Shows how many API requests are allowed in the current window for your client. In this case, the number is 25 requests. | -| `X-Rate-Limit-Requests-Left` | Details how many remaining requests your client can make in the current window before being rate limited. In this case, you would expect to be able to make 6 more requests in the next 3000 milliseconds; on the 7th request within 3000 milliseconds, you would be rate limited and would receive an HTTP 429 response.| +If your implementation's request to the API triggers a [429: Too Many Requests](/api-docs/getting-started/api-status-codes#4xx-client-error) response, it is encountering rate limits. Responses contain the `X-Rate-Limit-Time-Reset-Ms` header, which specifies the time in milliseconds that your client must wait before its quota refreshes. Retry the request after this time has elapsed. -You will know you've been limited if your request to the API triggers a [429: Too Many Requests](/api-docs/getting-started/api-status-codes#4xx-client-error) response. - -The rate limited response will contain the `X-Rate-Limit-Time-Reset-Ms` header, specifying a time (in milliseconds) that your client must wait before its quota has refreshed. Retry the request after this time has elapsed, and your API service will resume as normal. +For more about rate limit headers and how to calculate the timing of your requests to reduce the risk of encoutering rate limits, see [About Our API](/api-docs/getting-started/about-our-api#bigcommerce-specific-response-headers). ### Example of 429 status code When you see a response with an HTTP `429` status code, your client shouldn’t make any further requests until your quota has refreshed: ```http filename="Example: 429 response" showLineNumbers copy -HTTP/1.1 429 Too Many Requests -Date: Mon, 03 Feb 2022 20:36:00 GMT -Content-Type: application/json -X-Rate-Limit-Time-Reset-Ms: 15000 + HTTP/1.1 429 Too Many Requests + Date: Mon, 03 Feb 2022 20:36:00 GMT + Content-Type: application/json + X-Rate-Limit-Time-Reset-Ms: 15000 ``` Parse the `X-Rate-Limit-Time-Reset-Ms` header to determine how long you have to wait. In this case, it would be 15000 milliseconds. Your client can sleep on the specified interval: ```php filename="PHP example for delaying response" showLineNumbers copy - $milliseconds = $response->getHeader("X-Rate-Limit-Time-Reset-Ms"); - usleep($milliseconds * 1000); + $milliseconds = $response->getHeader("X-Rate-Limit-Time-Reset-Ms"); + usleep($milliseconds); ``` After waiting for the given number of milliseconds, your client can go back to making API requests. ### Making requests in parallel -You might wish to increase the amount of work your application can do in a given unit of time by sending multiple HTTP requests to the BigCommerce API in parallel. This is perfectly acceptable. However, your application should monitor the rate limiting headers to avoid an HTTP `429` response. Methods for doing this include: -* Slowing your rate of API requests when `X-Rate-Limit-Requests-Left` is nearing zero. -* Determining an acceptable average rate of requests, by dividing `X-Rate-Limit-Requests-Quota` by `X-Rate-Limit-Time-Window-Seconds`, and then self-throttling to that rate. - - Endpoints that accept bulk requests may have specific limitations on the number of accepted parallel requests. For example, making multiple parallel `upsert` requests to [`/pricelists/{price_list_id}/records`](/docs/rest-management/price-lists/price-lists-records#upsert-price-list-records) will result in a `429` error response. These limitations are documented at the operation level in the API reference. - +You can increase the amount of work your app can do in a given unit of time by sending multiple HTTP requests in parallel. This is perfectly acceptable. However, your app should monitor the rate limiting headers to avoid an HTTP `429` response. Methods for doing this include the following: +* Slowing your rate of API requests as `X-Rate-Limit-Requests-Left` approaches zero. +* Determining an acceptable average rate of requests by dividing `X-Rate-Limit-Requests-Quota` by `X-Rate-Limit-Time-Window-Ms`, and then self-throttling to that rate. -### Making requests with the Storefront Cart API -Client-side applications should avoid polling the [Storefront Cart API](/docs/rest-storefront/carts) on interval. Hundreds of thousands of browsers could potentially poll the Storefront Cart API at any given time, causing a significant load increase to BigCommerce's servers. We may take action against a store using this practice to prevent interruptions in service to other stores. +Endpoints that accept bulk requests may have specific limitations on the number of accepted parallel requests. For example, making multiple parallel requests to [Upsert price list records](/docs/rest-management/price-lists/price-lists-records#upsert-price-list-records) results in one or more error responses with the [429: Too Many Requests](/api-docs/getting-started/api-status-codes#4xx-client-error) status code. The current list of limitations is documented in our article on [resource-specific limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits#storelimits). The [API reference](/docs/api) specification for each endpoint or mutation also documents any limits specific to that request. -As an alternative, consider using a server-side application to subscribe to [cart webhook events](/api-docs/store-management/webhooks/webhook-events#carts), then query the Storefront Cart API only as a response to user input. Storing cart information in the browser cache is also an alternative method for keeping cart information up to date across browser tabs. +## Resources -## Platform limits +### API platform -BigCommerce does have limits on the number of products, categories, brands, etc. that can be created in a store. See [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) for more details. +* [Platform Limits (Help Center)](https://support.bigcommerce.com/s/article/Platform-Limits) +* [API Terms of Service (bigcommerce.com)](https://www.bigcommerce.com/terms/api-terms/) +* [Filtering Requests](/api-docs/getting-started/filtering) +* [API Status Codes](/api-docs/getting-started/api-status-codes) +* [About Our API: Response Headers](/api-docs/getting-started/about-our-api#response-headers) +* [Guide to API Accounts](/api-docs/getting-started/api-accounts)[webhook events and their payloads](/api-docs/store-management/webhooks/webhook-events) +* [Changelog](/changelog) ## Correlating requests -When building a headless storefront, it's best practice to group related requests using the `X-Correlation-Id` header. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#request-headers). For an example and a more in-depth explanation, see the [Introduction to Headless Commerce](/api-docs/storefronts/guide/overview#correlating-requests). +When building a headless storefront, it's best practice to group related requests using the `X-Correlation-Id` header. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#bigcommerce-specific-request-headers). For an example and a more in-depth explanation, see the [Introduction to Headless Commerce](/api-docs/storefronts/guide/overview#correlating-requests). ## Resources + ### Related articles -* [API Status Codes](/api-docs/getting-started/api-status-codes) -* [Filtering](/api-docs/getting-started/filtering) -* [Platform Limits](https://support.bigcommerce.com/s/article/Platform-Limits) + +* [Webhook Events](/api-docs/store-management/webhooks/webhook-events) +* [About Webhooks](/api-docs/getting-started/webhooks/about-webhooks) +* [Big Open Data Layer](/api-docs/partner/analytics-solutions/bodl#bodl-event-schemas) + +### API references and clients + +* [API Reference](/docs/api) +* [REST Storefront Cart API](/docs/rest-storefront/carts) +* [Upsert price list records](/docs/rest-management/price-lists/price-lists-records#upsert-price-list-records) +* [BigCommerce Ruby API client (GitHub)](https://github.com/bigcommerce/bigcommerce-api-ruby) + +### External articles + +* [429 status code reference (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) diff --git a/docs/api-docs/getting-started/making-requests.mdx b/docs/api-docs/getting-started/making-requests.mdx index 8594c70e8..8b32a1cbc 100644 --- a/docs/api-docs/getting-started/making-requests.mdx +++ b/docs/api-docs/getting-started/making-requests.mdx @@ -7,17 +7,17 @@ keywords: cors, This quick start guide will take you through making your first requests with BigCommerce's APIs. -## REST API +## REST Management API ### Create an API account -See [Authenticating BigCommerce's Rest APIs](/api-docs/getting-started/api-accounts) for instructions on creating API accounts. +See the [Guide to API Accounts](/api-docs/getting-started/api-accounts) for instructions on creating API accounts. ### Use Request Runner -The easiest way to experiment with BigCommerce REST APIs is using the **Request Runner** built in to the [API Reference](/docs/api) for most endpoints. +You can experiment with our REST Management APIs using the **Request Runner**, which is built in to the [API Reference](/docs/api) for most endpoints. -Just copy and paste your `store_hash` and `access_token` into the form, then click **Send**. +Copy and paste your `store_hash` and `access_token` into the form, then click **Send**. ### Visual Studio Code REST Client @@ -37,26 +37,30 @@ Accept: application/json Save and you'll see the **send request** link above `GET`. Click **send request** and the response will open in a split window. -### Import API spec file with Postman +### Postman -You can import many of our API Specification Files into [Postman](https://www.getpostman.com/) (or any other tool that can import [Open API Specification](https://swagger.io/specification/) files) to try out endpoints and view responses. +To try out REST endpoints and view responses, you can import our API specification files into [Postman](https://www.getpostman.com/) or any other tool that can import [Open API Specification](https://swagger.io/specification/) files. To view sample JSON request bodies for each REST API resource, see the [API Reference](/docs/api) for that resource. -## Storefront API quick start +## REST Storefront API quick start -To make your first requests in a browser with the Storefront APIs, see the step-by-step tutorial [Working with Storefront Cart and Checkout APIs](/api-docs/cart-and-checkout/working-sf-apis). +To make your first requests in a browser with the REST Storefront APIs, see the step-by-step tutorial [Working with Storefront Cart and Checkout APIs](/api-docs/cart-and-checkout/working-sf-apis). -## GraphQL API +## GraphQL Storefront API ### Create a storefront token -We'll use **Request Runner** for making an initial request to create a Storefront API token. It is a REST API request, so you will need to copy and paste your [API credentials](/api-docs/getting-started/api-accounts#creating-store-level-api-credentials). -Include the URL of the storefront you will be making the request from as the `allowed_cors_origin`. +This example uses **Request Runner** to make an initial request that creates a Storefront API token. It is a REST API request, so you will need to copy and paste your [API credentials](/api-docs/getting-started/api-accounts#creating-store-level-api-credentials). -**`POST`** `https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/api-token` +In the `allowed_cors_origins` array, include the URL(s) of the storefront from which you plan to use the token. + +```http filename="Example request: Create a storefront token" copy +POST https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/api-token +X-Auth-Token: {{access_token}} +Content-Type: application/json +Accept: application/json -```json { "channel_id": 1, // int (only ID 1 currently accepted) "expires_at": 1602288000, // double UTC unix timestamp in seconds (required) @@ -67,7 +71,8 @@ Include the URL of the storefront you will be making the request from as the `al ``` ### Create sample request in the browser -While viewing your storefront in a browser, navigate to the integrated JavaScript console; for example, [Google Chrome's Console](https://developers.google.com/web/tools/chrome-devtools/console). Use it to run the following code after entering your API token in the authorization header, and adding a valid [Product ID](/docs/rest-catalog/products#get-a-product) for the `entityId`: + +While viewing your storefront in a browser, open the developer tools JavaScript console; for example, [Google Chrome's Console](https://developers.google.com/web/tools/chrome-devtools/console). Add your API token to the authorization header in the following code sample and add a valid [Product ID](/docs/rest-catalog/products#get-a-product) for the `entityId`, then run the code in the console: ```js filename="Example query" copy showLineNumbers fetch('/graphql', { @@ -81,7 +86,7 @@ While viewing your storefront in a browser, navigate to the integrated JavaScrip body: JSON.stringify({ query: `query SingleProduct { site { - products (entityIds: product ID) { + products (entityIds: {{product ID}}) { edges { node { id diff --git a/docs/api-docs/headless/overview.mdx b/docs/api-docs/headless/overview.mdx index 3c76d4055..59adce9be 100644 --- a/docs/api-docs/headless/overview.mdx +++ b/docs/api-docs/headless/overview.mdx @@ -35,7 +35,7 @@ In the diagram below, the storefront is where the shopper interacts with product ## Correlating requests -Completing an operation on a headless storefront may require several API calls. For example, [processing a payment](/api-docs/store-management/payments-api-overview) and [refunding an order](/api-docs/store-management/order-refunds) each require reading and writing information using multiple endpoints. When you perform a multi-part operation on a headless storefront, group the constituent requests by generating one UUID to represent the whole operation, then use the `X-Correlation-Id` request header to send that UUID with every request in the group. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#request-headers). +Completing an operation on a headless storefront may require several API calls. For example, [processing a payment](/api-docs/store-management/payments-api-overview) and [refunding an order](/api-docs/store-management/order-refunds) each require reading and writing information using multiple endpoints. When you perform a multi-part operation on a headless storefront, group the constituent requests by generating one UUID to represent the whole operation, then use the `X-Correlation-Id` request header to send that UUID with every request in the group. This indicates to BigCommerce's infrastructure that an API call is part of a larger operation, and helps us track the handoff from request to request as the operation moves through our servers. To learn more about the header, see our [list of request headers](/api-docs/getting-started/about-our-api#bigcommerce-specific-request-headers). When you're using the BigCommerce for WordPress plugin, there is no need to send the `X-Correlation-Id` header. diff --git a/docs/stencil-docs/reference-docs/front-matter-reference.mdx b/docs/stencil-docs/reference-docs/front-matter-reference.mdx index 3a227fe9c..bf73eb62f 100644 --- a/docs/stencil-docs/reference-docs/front-matter-reference.mdx +++ b/docs/stencil-docs/reference-docs/front-matter-reference.mdx @@ -31,7 +31,7 @@ customer: |:---------|:------------| | `customer` | Customer attributes are always included and are available when an active shopper logs in. | | `returns` | Boolean indicating whether to retrieve product return requests for this customer. No filtering available.true: Retrieve requests. null or false: Do not retrieve requests. | -| `wishlists` | If `null`, wishlists are displayed. If `limit` is not specified, it retrieves an unlimited number of wishlists. | +| `wishlists` | If `null`, wishlists are displayed. If `limit` is not specified, it retrieves every wishlist. | | `orders` | If `null`, no orders are displayed. Displays complete and incomplete orders. If `limit` is not specified, it displays 20 orders. | | `recently_viewed_products` | Boolean indicating whether to display recently viewed products. No filtering available. | | `limit` | The maximum number of the entity to display. |