Difference between revisions of "API Metafield"

From Spiffy Stores Knowledge Base

Line 105: Line 105:
 
This is the name assigned to a set of unique metadata keys. Namespaces allow you to group and manage the metadata associated with the objects. A Namespace name has a maximum of 20 characters.
 
This is the name assigned to a set of unique metadata keys. Namespaces allow you to group and manage the metadata associated with the objects. A Namespace name has a maximum of 20 characters.
 
|-
 
|-
|handle
+
|key
|<code>{ "handle" : "cute-dog" }</code><br/>
+
|<code>{ "key" : "stock_location" }</code><br/>
A unique, human-friendly string for the product. Usually, the handle is automatically generated from its title. The handle is used in the product URL to refer to the product, and can also be used access the product from the API and in the store's templates.
+
The key identifies the associated metadata within the given namespace. It has a maximum of 30 characters.
 +
|-
 +
|value
 +
|<code>{ "value" : "Sydney" }</code><br/>
 +
This is the actual value of the metadata.
 +
|-
 +
|value_type
 +
|<code>{ "value_type" : "string" }</code><br/>
 +
The metadata value can be treated as either a ''string'' or an ''integer''.
 +
|-
 +
|description
 +
|<code>{ "description" : "This is where the product is physically located." }</code><br/>
 +
This is an optional property that can be used to document the use of the metadata.
 +
|-
 +
|owner_id
 +
|<code>{ "owner_id" : "345354354" }</code><br/>
 +
A unique numeric identifier for the owner of the metafield.
 +
|-
 +
|owner_resource
 +
|<code>{ "owner_resource" : "Product" }</code><br/>
 +
This is the type of resource that owns the metafield.
 
|}
 
|}

Revision as of 15:50, 18 February 2015

The Spiffy Stores API Metafield object allows you to attach metadata to a number of your Store's objects.

In this context, metadata represents any sort of data that can be represented by a key/value structure and can be associated with one of the following types of store objects.

  • Store
  • Product
  • Variation
  • Page
  • Blog
  • Standard Collection
  • Super Collection
  • Customer
  • Order

A Metafield has the following properties:

  • Namespace
  • Key
  • Value
  • Value Type (integer or string)
  • Description (Optional)

The Namespace allows you to group a number of related keys together.

Within a Namespace, there will be one or more unique Keys.

Each Key within the Namespace will have a Value which may be either an integer or string value.

Finally, for documentation purposes, an optional Description may also be added when the Metafield is created.

Metafields have many uses. For example, they allow you to store additional information about a product, that is specific to a certain type of product. You could use Metafields to associate products to a specific set of accessories for that product. Metafields provide a generic customization capabilities that allow you to organize your store's products, customers, orders and other content in any way that suits your particular needs.

Accessing a Metafield

Metafields can be created and associated with your Store. These sort of Metafields are global as only one instance of a store exists.

You can manage these sort of Metafields using the following types of API calls -

GET /api/metafields.json
GET /api/metafields/12345.json

and so on…

Metafields may also be associated with individual instances of store objects. In these cases, the Metafields are created when the object is created or added at a later time.

In order to manage these sort of Metafields, the object to which they belong must be referenced in the API call. For example -

GET /api/products/56789/metafields.json
GET /api/products/56789/metafields/24234.json

or

GET /api/variations/36789/metafields.json
GET /api/variations/36789/metafields/34523.json

or

GET /api/pages/234234/metafields.json
GET /api/pages/234234/metafields/456656.json

or

GET /api/blogs/86868/metafields.json
GET /api/blogs/86868/metafields/23423.json

or

GET /api/standard_collections/886789/metafields.json
GET /api/standard_collections/886789/metafields/67435.json

or

GET /api/super_collections/996789/metafields.json
GET /api/super_collections/996789/metafields/126575.json

or

GET /api/customers/56222/metafields.json
GET /api/customers/56222/metafields/12775.json

or

GET /api/orders/56111/metafields.json
GET /api/orders/56111/metafields/133325.json


Metafield Properties

id { "id" : 123456789 }

A unique numeric identifier for the metafield.

namespace { "namespace" : "accessories" }

This is the name assigned to a set of unique metadata keys. Namespaces allow you to group and manage the metadata associated with the objects. A Namespace name has a maximum of 20 characters.

key { "key" : "stock_location" }

The key identifies the associated metadata within the given namespace. It has a maximum of 30 characters.

value { "value" : "Sydney" }

This is the actual value of the metadata.

value_type { "value_type" : "string" }

The metadata value can be treated as either a string or an integer.

description { "description" : "This is where the product is physically located." }

This is an optional property that can be used to document the use of the metadata.

owner_id { "owner_id" : "345354354" }

A unique numeric identifier for the owner of the metafield.

owner_resource { "owner_resource" : "Product" }

This is the type of resource that owns the metafield.