Skip to content

Latest commit

 

History

History
129 lines (109 loc) · 5.55 KB

options_method.md

File metadata and controls

129 lines (109 loc) · 5.55 KB

Overview

The HTTP OPTIONS method can be used to discover the capabilities and requirements of resources in the Bigcommerce API. The OPTIONS method itself is defined as follows according to the HTTP/1.1 spec:

The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

The Bigcommerce API uses the OPTIONS method to describe the methods which are available for a certain resource (such as GET, POST, PUT and DELETE) as well as the resource-specific fields and their various properties. A smart or dynamic client can utilise this method to discover which methods are available for a resource, which fields are available or required for a method and the data requirements for each field.

Unless noted otherwise, the OPTIONS method is available for all Bigcommerce API resources.

The response headers for an OPTIONS request will contain an Allow header describing (as a CSV) a list of permitted HTTP methods for the requested resource, while the response-body will contain a list of fields entities as described below.

It is important to note that the methods and fields described by OPTIONS will most certainly differ between a listing resource and it's related entity resources (such as /brands.xml versus /brands/1.xml). This is demonstrated in the examples below.

Fields

API Field

API Data Type

Field Description

name

string

The name of the API field being described. This name maps directly to the input and output fields for the resource.

type

string

The API Data Type of the field being described. The types referred to by this field can be seen in the Data Types documentation.

length

int | string

For types which are limited in length, this described the length limitation of this field. For example, a string field with a length of 50 will only accept up to 50 characters, while a decimal field with a length of "20,4" will only accept numbers up to 20 total digits (including the digits after the decimal point). For more information, please refer to the Data Types documentation.

The length will not be present for field types where the length is not applicable (such as text fields and the various integer types).

writable_methods

array

A list of HTTP methods for which this field can be written to. This list may be empty for fields which are completely read-only - the id field is a typical example of this.

required_methods

array

A list of HTTP methods for which this field is a required field. For example, the name field on the brands resource is required for POST requests.

Examples

OPTIONS Response for a Listing Resource

An OPTIONS request on the optionsets listing may look something like this.

curl --user apiUsername:apiToken --request OPTIONS https://www.example.com/api/v2/optionsets.xml

HTTP/1.1 200 OK
Status: 200 OK
Allow: GET, POST, DELETE, HEAD, OPTIONS
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<options>
  <fields>
    <field>
      <name>id</name>
      <type>int</type>
      <writable_methods/>
      <required_methods/>
    </field>
    <field>
      <name>name</name>
      <type>string</type>
      <length>255</length>
      <writable_methods>
        <value>POST</value>
      </writable_methods>
      <required_methods>
        <value>POST</value>
      </required_methods>
    </field>
    <field>
      <name>options</name>
      <type>resource</type>
      <writable_methods/>
      <required_methods/>
    </field>
  </fields>
</options>

OPTIONS Response for an Entity Resource

An OPTIONS request on an optionsets entity resource may look something like this. Note the difference in the responses between /optionsets.xml and /optionsets/123.xml .

curl --user apiUsername:apiToken --request OPTIONS https://www.example.com/api/v2/optionsets/123.xml


<?xml version="1.0" encoding="UTF-8"?>
<options>
  <fields>
    <field>
      <name>id</name>
      <type>int</type>
      <writable_methods/>
      <required_methods/>
    </field>
    <field>
      <name>name</name>
      <type>string</type>
      <length>255</length>
      <writable_methods>
        <value>PUT</value>
      </writable_methods>
      <required_methods>
        <value>PUT</value>
      </required_methods>
    </field>
    <field>
      <name>options</name>
      <type>resource</type>
      <writable_methods/>
      <required_methods/>
    </field>
  </fields>
</options>