Difference between revisions of "API StandardCollection"
From Spiffy Stores Knowledge Base
(10 intermediate revisions by the same user not shown) | |||
Line 2: | Line 2: | ||
There are also super collections, which contain products based on selection conditions rather than been included in the collection manually. For more information, see [[API SuperCollection|SuperCollection]]. | There are also super collections, which contain products based on selection conditions rather than been included in the collection manually. For more information, see [[API SuperCollection|SuperCollection]]. | ||
+ | |||
+ | === Accessing a Standard Collection === | ||
+ | |||
+ | If you want to refer to a single Standard Collection, then you will need to use the unique standard collection id that has been assigned to that collection. These collection ids are returned when you request a list of the standard collections that belong to your store. | ||
+ | |||
+ | The standard collection ids are internally generated by the software and cannot be created or assigned. | ||
+ | |||
+ | Alternatively, you may specify the standard collection handle in place of the standard collection id when requesting access to a collection. The standard collection handle is the unique character string that is assigned to every collection when it is created. The handle is used in the URL to display the collection page. | ||
+ | |||
+ | For example, you may retrieve a standard collection in two ways. | ||
+ | |||
+ | <pre> | ||
+ | GET /api/standard_collections/12345678.json | ||
+ | |||
+ | or | ||
+ | |||
+ | GET /api/standard_collections/green-things.json | ||
+ | </pre> | ||
+ | |||
+ | The advantage of using the handle form of the request is that you don't need to search all the standard collections first in order to determine the standard collection 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 standard collections. | ||
== Standard Collection Properties == | == Standard Collection Properties == | ||
Line 118: | Line 138: | ||
|- | |- | ||
!fields | !fields | ||
− | |A comma-separated list of fields to return in the response. | + | |A comma-separated list of fields to return in the response. If a list of fields is provided, then the <code>images</code> field will always be excluded. |
|} | |} | ||
Line 219: | Line 239: | ||
</pre> | </pre> | ||
− | === <code>GET /api/ | + | === <code>GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json</code> === |
− | Retrieves a single standard collection by ID. | + | Retrieves a single standard collection by ID or handle. |
==== Optional Parameters ==== | ==== Optional Parameters ==== | ||
Line 227: | Line 247: | ||
{| class="reference" | {| class="reference" | ||
!fields | !fields | ||
− | |A comma-separated list of fields to return in the response. | + | |A comma-separated list of fields to return in the response. If a list of fields is provided, then the <code>images</code> field will always be excluded. |
|} | |} | ||
Line 233: | Line 253: | ||
<pre> | <pre> | ||
− | GET /api/ | + | GET /api/standard_collections/190.json |
HTTP/1.1 200 OK | HTTP/1.1 200 OK | ||
{ | { | ||
− | " | + | "standard_collection": { |
"id": 190, | "id": 190, | ||
"title": "Green Things", | "title": "Green Things", | ||
Line 273: | Line 293: | ||
</pre> | </pre> | ||
− | === <code>POST /api/ | + | === <code>POST /api/standard_collections.json</code> === |
Create a standard collection. | Create a standard collection. | ||
Line 280: | Line 300: | ||
<pre> | <pre> | ||
− | POST /api/ | + | POST /api/standard_collections.json |
{ | { | ||
− | " | + | "standard_collection": { |
"title": "My Latest Standard Collection", | "title": "My Latest Standard Collection", | ||
"body": "Buy these products. They're great!", | "body": "Buy these products. They're great!", | ||
Line 298: | Line 318: | ||
{ | { | ||
− | " | + | "standard_collection": { |
"id": 123490, | "id": 123490, | ||
"title": "My Latest Standard Collection", | "title": "My Latest Standard Collection", | ||
Line 325: | Line 345: | ||
</pre> | </pre> | ||
− | === <code>PUT /api/ | + | === <code>PUT /api/standard_collections/(STANDARD_COLLECTION_ID||STANDARD_COLLECTION_HANDLE).json</code> === |
Updates a standard collection. | Updates a standard collection. | ||
Line 332: | Line 352: | ||
<pre> | <pre> | ||
− | PUT /api/ | + | PUT /api/standard_collections/248.json |
{ | { | ||
− | " | + | "standard_collection": { |
"id": 248, | "id": 248, | ||
"published": false | "published": false | ||
Line 344: | Line 364: | ||
</pre> | </pre> | ||
− | === <code>DELETE /api/ | + | === <code>DELETE /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json</code> === |
Deletes a standard collection. | Deletes a standard collection. | ||
Line 351: | Line 371: | ||
<pre> | <pre> | ||
− | DELETE /api/ | + | DELETE /api/standard_collections/248.json |
HTTP/1.1 200 OK | HTTP/1.1 200 OK |
Latest revision as of 11:24, 22 August 2018
A standard collection is a grouping of products that you can create to help organize the items you have for sale and to help customers find your products. You create a standard collection and then select the products that will be listed in that collection.
There are also super collections, which contain products based on selection conditions rather than been included in the collection manually. For more information, see SuperCollection.
Contents
- 1 Accessing a Standard Collection
- 2 Standard Collection Properties
- 3 Endpoints
- 3.1 GET /api/standard_collections.json
- 3.2 GET /api/standard_collections/count.json
- 3.3 GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json
- 3.4 POST /api/standard_collections.json
- 3.5 PUT /api/standard_collections/(STANDARD_COLLECTION_ID||STANDARD_COLLECTION_HANDLE).json
- 3.6 DELETE /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json
- 4 Further Reference
Accessing a Standard Collection
If you want to refer to a single Standard Collection, then you will need to use the unique standard collection id that has been assigned to that collection. These collection ids are returned when you request a list of the standard collections that belong to your store.
The standard collection ids are internally generated by the software and cannot be created or assigned.
Alternatively, you may specify the standard collection handle in place of the standard collection id when requesting access to a collection. The standard collection handle is the unique character string that is assigned to every collection when it is created. The handle is used in the URL to display the collection page.
For example, you may retrieve a standard collection in two ways.
GET /api/standard_collections/12345678.json or GET /api/standard_collections/green-things.json
The advantage of using the handle form of the request is that you don't need to search all the standard collections first in order to determine the standard collection 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 standard collections.
Standard Collection Properties
id | { "id" : 155 } A unique numeric identifier for the standard collection. |
---|---|
title | { "title": "Green Things" } The title of the standard collection. |
handle | { "handle": "green-things" } A unique, human-friendly string for the standard collection, generated automatically from its title. In online store themes, the Liquid templating language refers to a standard collection by its handle. |
body | { "body": "This is a collection of green things." } The text content of the standard collection in Textile markup. This is automatically translated into body_html for display on a browser. |
body_html | { "body_html": "<p>This is a collection of green things.</p>" } The text content of the standard collection, complete with HTML markup. |
published | { "published" : true } Indicates whether the standard collection is published and visible to customers. |
sort_order | { "sort_order" : "alpha_a" } Indicates the default sorting order for the standard collection. This field has the following options:
|
products_count | { "products_count" : 41 } This is the number of products in the collection. |
created_at | { "created_at": "2008-07-15T20:00:00-04:00" } The date and time (ISO 8601 format) when the standard collection was created. |
updated_at | { "updated_at": "2008-07-16T20:00:00-04:00" } The date and time (ISO 8601 format) when the standard collection was last updated. |
images | { "images" : [ { "id": 2296, "product_id": 123456789, "position": 1, "alt": "", "filename": "chrysanthemum.jpg", "extension": "jpg", "digest": "71465638e6ee742dd0194de93b8efde3", "src": "http://server1.spiffystores.com/sites/4/products/123456789_chrysanthemum_full.jpg", "product_id": 123456789, "variation_ids": [1345, 6789] }, … ] } A list of all the standard collection images is returned. |
Endpoints
GET /api/standard_collections.json
Retrieve a list of all standard collections.
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. |
product_id | Limit the results to only include standard collections that include a given product. |
title | Limit the results to only include standard collections with the given title. |
handle | Limit the results to only include standard collections with the given handle. |
published_status | Limit the results to only include standard collections with the given published status ('published' or 'unpublished'). |
created_at_min | Return only the standard collections created after the given date and time. Use the format "2014-12-31 12:00". |
created_at_max | Return only the standard collections created before the given date and time. Use the format "2014-12-31 12:00". |
updated_at_min | Return only the standard collections updated after the given date and time. Use the format "2014-12-31 12:00". |
updated_at_max | Return only the standard collections updated before the given date and time. Use the format "2014-12-31 12:00". |
fields | A comma-separated list of fields to return in the response. If a list of fields is provided, then the images field will always be excluded.
|
Example Request and Response
GET /api/standard_collections.json HTTP/1.1 200 OK { "standard_collections": [ { "id": 155, "title": "Green Things", "handle": "green-things", "body": "Here is an introduction to the 'green things' collection. Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below. Search engines also enjoy reading this text.", "body_html": "<p>Here is an introduction to the 'green things' collection. Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below. Search engines also enjoy reading this text.</p>", "published": true, "sort_order": "manual", "products_count": 15, "created_at": "2008-07-16T08:18:54.000+10:00", "updated_at": "2016-02-26T11:24:17.276+11:00", "images": [ { "id": 2335, "position": 1, "alt": "Test", "filename": "sale.jpg", "extension": "jpg", "digest": "c0580b5987ae39bcb9134074352d3b98", "src": "https://test.spiffystores.com/sites/1/collections/155_sale_full.jpg?v=c0580b5987ae39bcb9134074352d3b98" }, { "id": 2332, "position": 2, "alt": "", "filename": "koala.jpg", "extension": "jpg", "digest": "2fd63d15d3530099d69d1c82ffbcc76c", "src": "https://test.spiffystores.com/sites/1/collections/155_koala_full.jpg?v=2fd63d15d3530099d69d1c82ffbcc76c" } ] }, ... ] } Examples using filters GET /api/standard_collections.json?fields=id,title
GET /api/standard_collections/count.json
Return a count of the number of standard collections.
Optional Parameters
since_id | Limit the results to only include objects which have an id greater than the given value. |
---|---|
product_id | Limit the results to only include standard collections that include a given product. |
title | Limit the results to only include standard collections with the given title. |
handle | Limit the results to only include standard collections with the given handle. |
published_status | Limit the results to only include standard collections with the given published status ('published' or 'unpublished'). |
created_at_min | Return only the standard collections created after the given date and time. Use the format "2014-12-31 12:00". |
created_at_max | Return only the standard collections created before the given date and time. Use the format "2014-12-31 12:00". |
updated_at_min | Return only the standard collections updated after the given date and time. Use the format "2014-12-31 12:00". |
updated_at_max | Return only the standard collections updated before the given date and time. Use the format "2014-12-31 12:00". |
Example Request and Response
GET /api/standard_collections/count.json HTTP/1.1 200 OK { "count": 15 }
GET /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json
Retrieves a single standard collection by ID or handle.
Optional Parameters
fields | A comma-separated list of fields to return in the response. If a list of fields is provided, then the images field will always be excluded.
|
---|
Example Request and Response
GET /api/standard_collections/190.json HTTP/1.1 200 OK { "standard_collection": { "id": 190, "title": "Green Things", "handle": "green-things", "body": "Here is an introduction to the 'green things' collection. Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below. Search engines also enjoy reading this text.", "body_html": "<p>Here is an introduction to the 'green things' collection. Each collection should have a short introduction so that visitors can see what it's about by quickly scanning your intro text and looking at the product pictures displayed below. Search engines also enjoy reading this text.</p>", "published": true, "sort_order": "manual", "products_count": 15, "created_at": "2008-07-16T08:18:54.000+10:00", "updated_at": "2016-02-26T11:24:17.276+11:00", "images": [ { "id": 2335, "position": 1, "alt": "Test", "filename": "sale.jpg", "extension": "jpg", "digest": "c0580b5987ae39bcb9134074352d3b98", "src": "https://test.spiffystores.com/sites/1/collections/155_sale_full.jpg?v=c0580b5987ae39bcb9134074352d3b98" }, { "id": 2332, "position": 2, "alt": "", "filename": "koala.jpg", "extension": "jpg", "digest": "2fd63d15d3530099d69d1c82ffbcc76c", "src": "https://test.spiffystores.com/sites/1/collections/155_koala_full.jpg?v=2fd63d15d3530099d69d1c82ffbcc76c" } ] } }
POST /api/standard_collections.json
Create a standard collection.
Example Request and Response
POST /api/standard_collections.json { "standard_collection": { "title": "My Latest Standard Collection", "body": "Buy these products. They're great!", "published": true, "images": [ "attachment": "...", # Image data "filename": "test_image.jpg", "alt": "A picture of a Standard Product" ] } } HTTP/1.1 201 Created { "standard_collection": { "id": 123490, "title": "My Latest Standard Collection", "handle": "my-latest-standard-collection", "body": "Buy these products. They're great!", "body_html": "<p>Buy these products. They're great!</p>", "published": true, "sort_order": "manual", "products_count": 0, "created_at": "2018-07-16T08:18:54.000+10:00", "updated_at": "2018-07-16T08:18:54.000+10:00", "images": [ { "id": 23334534, "position": 1, "alt": "A picture of a Standard Product", "filename": "test_image.jpg", "extension": "jpg", "digest": "c0580b5987ae39bcb9134074352d3b98", "src": "https://test.spiffystores.com/sites/1/collections/155_test_image.jpg?v=c0580b5987ae39bcb9134074352d3b98" } ] } }
PUT /api/standard_collections/(STANDARD_COLLECTION_ID||STANDARD_COLLECTION_HANDLE).json
Updates a standard collection.
Example Request and Response
PUT /api/standard_collections/248.json { "standard_collection": { "id": 248, "published": false } } HTTP/1.1 200 OK
DELETE /api/standard_collections/(STANDARD_COLLECTION_ID|STANDARD_COLLECTION_HANDLE).json
Deletes a standard collection.
Example Request and Response
DELETE /api/standard_collections/248.json HTTP/1.1 200 OK {}