Difference between revisions of "API Image"
From Spiffy Stores Knowledge Base
Line 53: | Line 53: | ||
|<code><nowiki>{ "src" : "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg?6afd63d069abc37a673dd3927e283633" }</nowiki></code><br/> | |<code><nowiki>{ "src" : "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg?6afd63d069abc37a673dd3927e283633" }</nowiki></code><br/> | ||
Specifies the full URL for the image. | Specifies the full URL for the image. | ||
+ | |- | ||
+ | !variation_ids | ||
+ | |<code>{ "variation_ids" : [ 5595 ] }</code><br/> | ||
+ | This is an array of variation ids that are associated with this image. | ||
|- | |- | ||
!product_id | !product_id |
Revision as of 11:03, 22 August 2018
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.
Contents
- 1 Accessing a Product, StandardCollection or SuperCollection
- 2 Image Properties
- 3 Endpoints
- 3.1 GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/images.jsonGET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.jsonGET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
- 3.2 GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/count.jsonGET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.jsonGET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
- 3.3 GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonGET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonGET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
- 3.4 POST /api/products/(OBJECT_ID|OBJECT_HANDLE)/images.jsonPOST /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.jsonPOST /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
- 3.5 PUT /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonPUT /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonPUT /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
- 3.6 DELETE /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonDELETE /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.jsonDELETE /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
- 4 Further Reference
Accessing a Product, StandardCollection or SuperCollection
If you want to refer to a single Product, StandardCollection or SuperCollection then you will need to use the unique id that has been assigned to that object.
The object ids are internally generated by the software and cannot be created or assigned.
Alternatively, you may specify the object handle in place of the object id when requesting access to the object. The handle is the unique character string that is assigned to every product, standard or super collection when it is created. The handle is used in the URL to display the product or collection page.
For example, you may retrieve a product's images in two ways.
GET /api/products/12345678/images.json or GET /api/products/cute-dog/images.json
The advantage of using the handle form of the request is that you don't need to search all the products first in order to determine the product id, as you will already know what the handle is. This will reduce the number of API calls that you need to make and greatly simplifies the amount of coding that is needed to manage your products.
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. |
extension | { "extension" : "jpg" } This is the filename extension of the image. |
digest | { "digest" : "3b07e960a69232b2b9bf6a1d6262ddd5" } This is the unique hash associated with this image. It is based on the file name, contents and time of creation, so it can be used to ensure that old images are not being cached. |
src | { "src" : "http://server1.spiffystores.com/sites/4/products/123456789_cute_puppy_full.jpg?6afd63d069abc37a673dd3927e283633" } Specifies the full URL for the image. |
variation_ids | { "variation_ids" : [ 5595 ] } This is an array of variation ids that are associated with this 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/(OBJECT_ID|OBJECT_HANDLE)/images.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
GET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
GET /api/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. |
fields | A comma-separated list of fields to return in the response. |
Example Request and Response
GET /api/products/123456789/images.json HTTP/1.1 200 OK { "images" : [ { "id": 2321, "position": 1, "alt": "", "filename": "penguins.jpg", "extension": "jpg", "digest": "3b07e960a69232b2b9bf6a1d6262ddd5", "src": "http://server1.spiffystores.com/sites/4/products/123456789_penguins_full.jpg?936fec7af78d49584087eed3339c4e13", "product_id": 123456789 }, { "id": 2324, "position": 2, "alt": "", "filename": "jellyfish.jpg", "extension": "jpg", "digest": "a9bb53e17f7c24cbf641cf520a82b757", "src": "http://server1.spiffystores.com/sites/4/products/123456789_jellyfish_full.jpg?cfe2abb2c206c8ad0196d84e53b100a0", "product_id": 123456789 } ] } Examples using filters GET /api/products/123456789/images.json?fields=id,src Alternative form GET /api/products/fluffy-puppy/images.json GET /api/standard_collections/home-collection/images.json GET /api/super_collections/featured-collection/images.json
GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
GET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
GET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/count.json
Return a count of images.
Optional Parameters
since_id | Limit the results to only include objects which have an id greater than the given value. |
---|
Example Request and Response
GET /api/products/fluffy-puppy/images/count.json HTTP/1.1 200 OK { "count": 2 } Examples using filters GET /api/products/123456789/images/count.json?since_id=1000
GET /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
GET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
GET /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
GET /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
Return a single image.
Optional Parameters
fields | A comma-separated list of fields to return in the response. |
---|
Example Request and Response
GET /api/products/123456789/images/87675.json HTTP/1.1 200 OK { "image": { "id": 87675, "position": 1, "alt": "Another puppy photo", "filename": "fluffy_puppy.jpg", "src": "http://server1.spiffystores.com/sites/4/products/123456789_fluffy_puppy_full.jpg?453878e23ef050ecfa375609a903bb4e", "product_id": 123456789 } } Alternative form GET /api/products/cute-puppy/images/87675.json
POST /api/products/(OBJECT_ID|OBJECT_HANDLE)/images.json
POST /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
POST /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
POST /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
POST /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images.json
Create a new image.
You can create new images 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/fluffy-puppy/images.json { "image": { "src": "http://www.cute-puppies-r-us.com/images/fluffy_puppy.jpg", "filename": "fluffy_puppy.jpg", "alt": "So cute and cuddly", "position": 1 } } HTTP/1.1 201 Created
PUT /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
PUT /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
PUT /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
PUT /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
PUT /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
Update an image.
When you update an image, you must include the id
parameter, which must match the image_id specified in the POST URL.
You can only update the alt
and position
parameters. You cannot change the actual image or its filename. If you want to replace an image, then the existing image should be deleted and a new one created.
Example Request and Response
PUT /api/products/123456789/images/45678.json { "image": { "id": 45678, "alt": "This is new alt text", "position": 2 } } HTTP/1.1 200 OK
DELETE /api/products/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
DELETE /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
DELETE /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
DELETE /api/standard_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
DELETE /api/super_collections/(OBJECT_ID|OBJECT_HANDLE)/images/IMAGE_ID.json
Delete an image.
Example Request and Response
DELETE /api/products/123456789/images/45678.json HTTP/1.1 200 OK {} Alternative form DELETE /api/products/cute-puppy/images/45678.json