API Image

From Spiffy Stores Knowledge Base

Revision as of 11:40, 20 November 2014 by Admin (talk | contribs) (→‎GET /api/products.json)

The Spiffy Stores API Image object represents an image that may belong to either a product or a collection. Images can be in either .png, .gif or .jpg format.

You can view a product or collection's images, update them, create new ones, and delete them.

Image Properties

id { "id" : 123456789 }

A unique numeric identifier for the image.

position { "position" : 1 }

The position of the image in the ordered list of images. The first image has a position of 1 and is the main image for the product or collection.

alt { "alt" : "This is the alt text for the image" }

Images may have some associated alternative text which can be used when the image can't be displayed. It also provided additional information for screen readers and search engines.

filename { "filename" : "cute-puppy.jpg" }

The filename of the image is the base name of the image file as originally uploaded.

src { "src" : "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg?6afd63d069abc37a673dd3927e283633" }

Specifies the full URL for the image.

product_id { "product_id" : 123456789 }

The id of the image's associated product.

collection_id { "collection_id" : 123456789 }

The id of the image's associated collection.

Endpoints

GET /api/(products|standard_collections|super_collections)/(OBJECT_ID|OBJECT_HANDLE)/images.json

Return a list of images belonging to either a product, standard collection or super collection.

Optional Parameters

limit Number of results returned. The default is 30, with a maximum of 50 in a single request.
page The number of the page to return. The number of results per page is set by the limit parameter. If more results are required, then submit the request again, increasing the page number each time.
since_id Limit the results to only include objects which have an id greater than the given value.
vendor Limit the results to only include products supplied by the given vendor.
product_type Limit the results to only include products that belong to the given product_type.
handle Return the product with the given handle
collection_id Return only the products that belong to the given collection.
created_at_min Return only the products created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the products created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the products updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the products updated before the given date and time. Use the format "2014-12-31 12:00".
published_status Return only products with the given published status.
  • published - Include only published products
  • unpublished - Include only unpublished products
  • any - Include all products (default)
featured_status Return only products with the given featured status.
  • featured - Include only featured products
  • any - Include all products (default)
archived_status Return only products with the given archived status.
  • archived - Include only archived products
  • any - Include all products (default)
fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products.json

HTTP/1.1 200 OK

{
  "products": [
    { 
      "id": 123456789,
      "title": "Cute Puppy",
      "handle": "cute-puppy",
      "body": "A very cute puppy.",
      "body_html": "<p>A very cute puppy.</p>",
      "shipping_code": "",
      "created_at": "2012-03-28T17:53:26Z",
      "updated_at": "2014-01-16T05:50:56Z",
      "tags": ["cute", "puppy", "dog", "brown dog"],
      "published": true,
      "featured": true,
      "archived": false,
      "product_type": "Dog",
      "vendor": "Spiffy Stores",
      "options": [
        {
          "name": "Title",
          "position": 1
        }
      ],
      "custom_options": [],
      "images": [
        {
          "id": 1603342682,
          "position": 1,
          "alt": "This is a test product",
          "filename": "cute_puppy.jpg",
          "src": "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg"
        }
      ],
      "variations": [
        {
          "id": 28234540068,
          "title": "Default",
          "position": 1,
          "sku": "B3300",
          "barcode": "",
          "price": "139.8",
          "wholesale_price": "0.0",
          "compare_at_price": "0.0",
          "discount": "0.0",
          "taxable": true,
          "instalments": 1,
          "grams": 2000.0,
          "length": 0.0,
          "width": 0.0,
          "height": 0.0,
          "inventory_quantity": 5,
          "old_inventory_quantity": 5,
          "inventory_policy": "deny",
          "inventory_management": "spiffy",
          "fulfilment_service": "manual",
          "shipping_code": "",
          "free_shipping": false,
          "requires_shipping": true,
          "ship_separately": false,
          "created_at": "2012-03-28T17:53:26Z",
          "updated_at": "2014-01-16T05:50:56Z"
        }
      ]
    }, ...
  ]   
}

Examples using filters

GET /api/products.json?fields=id,title,images

GET /api/products.json?collection_id=23238768

GET /api/products/count.json

Return a count of products.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
vendor Limit the results to only include products supplied by the given vendor.
product_type Limit the results to only include products that belong to the given product_type.
handle Return the product with the given handle
collection_id Return only the products that belong to the given collection.
created_at_min Return only the products created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the products created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the products updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the products updated before the given date and time. Use the format "2014-12-31 12:00".
published_status Return only products with the given published status.
  • published - Include only published products
  • unpublished - Include only unpublished products
  • any - Include all products (default)
featured_status Return only products with the given featured status.
  • featured - Include only featured products
  • any - Include all products (default)
archived_status Return only products with the given archived status.
  • archived - Include only archived products
  • any - Include all products (default)

Example Request and Response

GET /api/products/count.json

HTTP/1.1 200 OK

{
  "count": 578
}

Examples using filters

GET /api/products/count.json?collection_id=234293847

GET /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json

Return a single product.

Optional Parameters

fields A comma-separated list of fields to return in the response.

Example Request and Response

GET /api/products/123456789.json

HTTP/1.1 200 OK

{
  "product": 
    { 
      "id": 123456789,
      "title": "Cute Puppy",
      "handle": "cute-puppy",
      "body": "A very cute puppy.",
      ...
    }
}

Alternative form

GET /api/products/cute-puppy.json

POST /api/products.json

Create a new product.

You can include images for the new product, either by including the image as Base64 data using the attachment tag, or by including a URL to the image which can be used to download the image using the src tag.

Example Request and Response

POST /api/products.json

{
  "product": {
    "title": "Brand New Product",
    "body": "A must for every home.",
    "vendor": "Big Brand",
    "product_type": "Gadget",
    "tags": "yellow, gadget, blue, home",
    "variations": [
      {
        "option1": "Large",
        "option2": "Yellow",
        "price": "10.00",
        "sku": "123",
        "inventory_quantity": 100
      },
      {
        "option1": "Small",
        "option2": "Blue",
        "price": "20.00",
        "sku": "456",
        "inventory_quantity": 50
      }
    ],
    "options": [
      { 
        "name": "Size",
        "position": 1
      },
      { 
        "name": "Colour",
        "position": 2
      }

    ],
    "images": [
      {
        "attachment": "R0lGODlhAQABAIAAAAAAAAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==\n",
        "filename": "cute_puppy.jpg"
      },
      {
        "src": "http://www.puppies-r-us.com/images/cute_puppy2.jpg",
        "filename": "cute_puppy2.jpg"
      }
    ]
  }
}

HTTP/1.1 201 Created

PUT /api/products/PRODUCT_ID.json

Update a product and associated images and variations.

You can include images for the updated product, either by including the image as Base64 data using the attachment tag, or by including a URL to the image which can be used to download the image using the src tag.

When you update a product, you must include the id parameter, which must match the product_id specified in the POST URL.

You can update any of the product properties by including the parameter in the PUT data. All other product properties remain unchanged.

You cannot change the number of options. Only the name of the option can be updated.

Product variations, custom_options and images cannot be individually updated using this API. If you specify any new variations, custom_options or images, then all existing variations, custom_options or images are deleted and replaced by the new variations, custom_options or images provided by this API.

Individual variations and images can be updated using the specific API calls for Variations and Images.

Example Request and Response

PUT /api/products/123456789.json

{
  "product": {
    "id": 123456789,
    "title": "This is a new title"
  }
}

HTTP/1.1 200 OK

DELETE /api/products/(PRODUCT_ID|PRODUCT_HANDLE).json

Delete a product and all associated images and variations.

Example Request and Response

DELETE /api/products/123456789.json

HTTP/1.1 200 OK

{}

Alternative form

DELETE /api/products/cute-puppy.json

Further Reference

Retrieved from "http://www.spiffystores.com.au/kb/index.php?title=API_Image&oldid=4990"