Skip to content

Latest commit

 

History

History
186 lines (125 loc) · 5.2 KB

README.md

File metadata and controls

186 lines (125 loc) · 5.2 KB
Raw

Webflow JS SDK

npm shield fern shield

The Webflow JavaScript SDK provides convenient access to the Webflow Data API from applications written in JS.

The SDK contains typings and request builders for the Webflow Data API.

Documentation

Explore the API reference documentation.

V2 Migration Guide

The SDK was rewritten in V2 and is now programatically generated from our OpenAPI spec. As part of this release there are some breaking changes.

Client Instantiation

The SDK exports WebflowClient instead of Webflow. The client now takes accessToken instead of token.

const webflow = new WebflowClient({ accessToken: "..." });

Oauth

The WebflowClient exports static methods that you can use for OAuth. These were previously on Webflow.

webflow.authorizeUrl -> WebflowClient.authorizeURL

webflow.accessToken -> WebflowClient.getAccessToken

webflow.revokeToken -> WebflowClient.revokeToken

HTTP Client

The SDK no longer uses Axios and defaults to fetch. The SDK supports multiple runtimes and will handle using a fetch implementation if available or will default to node-fetch.

Resources

Previously the SDK only supported the most important resources, such as site and user. Now the SDK supports methods on a variety of different endpoints such as collections, assets, forms, inventory, orders, etc.

Installation

Add this dependency to your project's package.json file:

Using npm:

$ npm install webflow-api

Using yarn

$ yarn add webflow-api

Usage

Simply import Webflow and start making calls to our API.

import { WebflowClient } from "webflow-api";

const webflow = new WebflowClient({ accessToken });

const site = await webflow.sites.get("site-id");

OAuth

To implement OAuth, you'll need to register a Webflow App in your Workspace

Step 1: Authorize URL

The first step in OAuth is to generate an Authorization URL. Use this URL to fetch your Authorization Code. See the docs for more details.

import { WebflowClient } from "webflow-api";

const authorizeUrl = WebflowClient.authorizeURL({
    state: "your_state",
    scope: "sites:read",
    clientId: "your_client_id",
    redirctUri: "your_redirect_uri",
});

console.log(authorizeUrl);

Step 2: Retrieve your access token

Use the getAccessToken function and pass in your client_id, client_secret, and authorization_code.

import { WebflowClient } from "webflow-api";

const accessToken = WebflowClient.getAccessToken({
  clientId: "your_client_id", 
  clientSecret: "your_client_secret",
  code: "your_authorization_code"
});

Step 3: Instantiate the client

Instantiate the client using your access_token.

import { WebflowClient } from "webflow-api";

const webflow = WebflowClient({ accessToken });

Webflow Types

All of the types are nested within the Webflow namespace. Let IntelliSense guide you!

Exception Handling

All errors thrown by the SDK will be subclasses of WebflowError.

import { WebflowClient, Webflow } from 'webflow';
const webflow = new WebflowClient({ accessToken: 'your_access_token' });

try {
  const sites = await webflow.sites.get(...);
} catch (e) {
  if (e instanceof Webflow.ForbiddenError) {
    console.log(e.body.message);
  } else if (e instanceof Webflow.BadRequestError) {
    console.log(e.body.message);
  } else {
    throw e;
  }
}

Advanced

Timeouts

By default, requests time out after 60 seconds. You can configure the timeout and # of max retries

import { WebflowClient } from 'webflow';

const sites = await webflow.sites.get(..., {
  timeoutInSeconds: 30 // override the timeout
});

Retries

The SDK will automatically retry failures with exponential backoff. You can configure the retries by setting maxRetries.

import { WebflowClient } from 'webflow';

const sites = await webflow.sites.get(..., {
  maxRetries: 10 // override the retries
});

Beta Status

This SDK is in Preview, and there may be breaking changes between versions without a major version update.

To ensure a reproducible environment (and minimize risk of breaking changes), we recommend pinning a specific package version.

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!