woocommerce/tests/e2e/api
Greg 7fe341f144 Update statusCode to status 2021-10-14 15:45:39 -06:00
..
src Finish work on order; removed unused variable from test 2021-05-03 20:21:00 -06:00
.eslintignore Renamed the `@woocommerce/factories` package to `@woocommerce/api` 2020-09-03 12:28:17 -07:00
.eslintrc.js Added @template JSDoc tag to API package for better IDE support 2020-09-29 12:00:09 -07:00
.gitignore Renamed the `@woocommerce/factories` package to `@woocommerce/api` 2020-09-03 12:28:17 -07:00
CHANGELOG.md release api package 0.2.0 (#29930) 2021-05-25 16:00:56 +02:00
README.md Update statusCode to status 2021-10-14 15:45:39 -06:00
jest.config.js Added settings and group repositories with some basic functionality 2020-09-30 13:11:31 -07:00
package-lock.json Merge pull request #30660 from woocommerce/dependabot/npm_and_yarn/tests/e2e/api/axios-0.21.2 2021-10-13 16:48:59 -03:00
package.json Bump axios from 0.19.2 to 0.21.2 in /tests/e2e/api 2021-09-28 18:26:35 +00:00
tsconfig.json Updated the JSDoc and type-safety of repositories to better document the implemented operations 2020-09-24 14:22:38 -07:00

README.md

WooCommerce API Client

An isometric API client for interacting with WooCommerce installations. Here are the current and planned features:

  • TypeScript Definitions
  • Axios API Client with support for OAuth & basic auth
  • Repositories to simplify interaction with basic data types
  • Service classes for common activities such as changing settings

Usage

npm install @woocommerce/api --save-dev

Depending on what you're intending to get out of the API client there are a few different ways of using it.

REST API

The simplest way to use the client is directly:

import { HTTPClientFactory } from '@woocommerce/api';

// You can create an API client using the client factory with pre-configured middleware for convenience.
let client = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

// You can also create an API client configured for requests using OAuth.
client = HTTPClientFactory.build( 'https://example.com' )
    .withOAuth( 'consumer_secret', 'consumer_password' )
    .create();

// You can then use the client to make API requests.
client.get( '/wc/v3/products' ).then( ( response ) => {
  // Access the status code from the response.
  response.status;
  // Access the headers from the response.
  response.headers;
  // Access the data from the response, in this case, the products.
  response.data;
}, ( error ) => {
  // Handle errors that may have come up.
} );

Repositories

As a convenience utility we've created repositories for core data types that can simplify interacting with the API:

Parent/Base Repositories

  • SimpleProduct
  • ExternalProduct
  • GroupedProduct
  • VariableProduct
  • Coupon
  • Order
  • SettingsGroup

Child Repositories

  • ProductVariation
  • Setting

These repositories provide CRUD methods for ease-of-use:

import { HTTPClientFactory, SimpleProduct } from '@woocommerce/api';

// Prepare the HTTP client that will be consumed by the repository.
// This is necessary so that it can make requests to the REST API.
const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .create();

const repository = SimpleProduct.restRepository( httpClient );

// The repository can now be used to create models.
const product = repository.create( { name: 'Simple Product', regularPrice: '9.99' } );

// The response will be one of the models with structured properties and TypeScript support.
product.id;

Repository Methods

The following methods are available on all repositories if the corresponding method is available on the API endpoint:

  • create( {...properties} ) - Create a single object of the model type
  • delete( objectId ) - Delete a single object of the model type
  • list( {...parameters} ) - Retrieve a list of the existing objects of that model type
  • read( objectId ) - Read a single object of the model type
  • update( objectId, {...properties} ) - Update a single object of the model type

Child Repositories

In child model repositories, each method requires the parentId as the first parameter:

import { HTTPClientFactory, VariableProduct, ProductVariation } from '@woocommerce/api';

const httpClient = HTTPClientFactory.build( 'https://example.com' )
    .withBasicAuth( 'username', 'password' )
    .withIndexPermalinks()
    .create();

const productRepository = VariableProduct.restRepository( httpClient );
const variationRepository = ProductVariation.restRepository( httpClient );

const product = await productRepository.create({
    "name": "Variable Product with Three Attributes",
    "defaultAttributes": [
    {
     "id": 0,
     "name": "Size",
     "option": "Medium"
    },
    {
     "id": 0,
     "name": "Colour",
     "option": "Blue"
    }
    ],
    "attributes": [
    {
     "id": 0,
     "name": "Colour",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Red",
       "Green",
       "Blue"
     ],
     "sortOrder": 0
    },
    {
     "id": 0,
     "name": "Size",
     "isVisibleOnProductPage": true,
     "isForVariations": true,
     "options": [
       "Small",
       "Medium",
       "Large"
     ],
     "sortOrder": 0
   }
  ]
});

const variation = await variationRepository.create( product.id, {
    "regularPrice": "19.99",
    "attributes": [
      {
        "name": "Size",
        "option": "Large"
      },
      {
        "name": "Colour",
        "option": "Red"
      }
    ]
});