Difference between revisions of "API Article"

From Spiffy Stores Knowledge Base

(Created page with "The Spiffy Stores API Article object represents a single article in a blog. Articles appear in reverse chronological order, with the most recent entry at the top of the blog's...")
 
m
Line 1: Line 1:
−
The Spiffy Stores API Article object represents a single article in a blog. Articles appear in reverse chronological order, with the most recent entry at the top of the blog's page. A blog can contain any number of articles.
+
An article is a single entry in a blog.
 +
 
 +
Articles appear in reverse chronological order, with the most recent entry at the top of the blog's page. An article belongs to only one blog.
 +
 
 +
== Article Properties ==
 +
 
 +
{| class="reference"
 +
!id
 +
|<pre>{ "id" : 191 }</pre>
 +
A unique numeric identifier for the article.
 +
|-
 +
!blog_id
 +
|<pre>{ "blog_id" : 472 }</pre>
 +
A unique numeric identifier for the blog that the article belongs to.
 +
|-
 +
!title
 +
|<pre>{ "title": "My First Article" }</pre>
 +
The title of the article.
 +
|-
 +
!handle
 +
|<pre>{ "handle": "my-first-article" }</pre>
 +
A unique, human-friendly string for the article, generated automatically from its title. In online store themes, the Liquid templating language refers to a article by its handle.
 +
|-
 +
!author
 +
|<pre>{ "author": "Bilbo Baggins" }</pre>
 +
The author of the article.
 +
|-
 +
!body
 +
|<pre>{ "body": "This is a test blog article" }</pre>
 +
The text content of the article in Textile markup. This is automatically translated into body_html for display on a browser.
 +
|-
 +
!body_html
 +
|<pre>{ "body_html": "<p>This is a test blog article</p>" }</pre>
 +
The text content of the article, complete with HTML markup.
 +
|-
 +
!created_at
 +
|<pre>{ "created_at": "2008-07-15T20:00:00-04:00" }</pre>
 +
The date and time (ISO 8601 format) when the article was created.
 +
|-
 +
!updated_at
 +
|<pre>{ "updated_at": "2008-07-16T20:00:00-04:00" }</pre>
 +
The date and time (ISO 8601 format) when the article was last updated.
 +
|-
 +
!published
 +
|<pre>{ "published" : true }</pre>
 +
Indicates whether the blog is published and visible to customers.
 +
|-
 +
!published_at
 +
|<pre>{ "published_at": "2008-07-16T20:00:00-04:00" }</pre>
 +
The date and time (ISO 8601 format) when the article was published.
 +
|}
 +
 
 +
== Endpoints ==
 +
 
 +
=== <code>GET /api/blogs/BLOG_ID/articles.json</code> ===
 +
 
 +
Retrieve a list of all articles belonging to the blog.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!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 <code>limit</code> 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.
 +
|-
 +
!title
 +
|Limit the results to only include articles with the given title.
 +
|-
 +
!handle
 +
|Limit the results to only include articles with the given handle.
 +
|-
 +
!author
 +
|Limit the results to only include articles written by the given author.
 +
|-
 +
!published_status
 +
|Limit the results to only include articles with the given published status ('published' or 'unpublished').
 +
|-
 +
!created_at_min
 +
|Return only the articles created after the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!created_at_max
 +
|Return only the articles created before the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!updated_at_min
 +
|Return only the articles updated after the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!updated_at_max
 +
|Return only the articles 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.
 +
|}
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
GET /api/blogs/BLOG_ID/articles.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{
 +
  "articles": [
 +
    {
 +
      "id": 190,
 +
      "blog_id": 472,
 +
      "title": "Test API blog article",
 +
      "handle": "test-api-blog-article",
 +
      "author": "Bilbo Baggins",
 +
      "body": "This is a test blog article",
 +
      "body_html": "<p>This is a test blog article</p>",
 +
      "created_at": "2016-03-30T17:10:44.992+11:00",
 +
      "updated_at": "2016-03-30T17:10:44.992+11:00",
 +
      "published": true,
 +
      "published_at": "2016-03-30T17:10:44.986+11:00"
 +
    }, ...
 +
  ]
 +
}
 +
 
 +
Examples using filters
 +
 
 +
GET /api/blogs/BLOG_ID/articles.json?fields=id,title
 +
 
 +
</pre>
 +
 
 +
=== <code>GET /api/blogs/BLOG_ID/articles/count.json</code> ===
 +
 
 +
Return a count of the number of articles.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!since_id
 +
|Limit the results to only include objects which have an id greater than the given value.
 +
|-
 +
!title
 +
|Limit the results to only include articles with the given title.
 +
|-
 +
!handle
 +
|Limit the results to only include articles with the given handle.
 +
|-
 +
!author
 +
|Limit the results to only include articles written by the given author.
 +
|-
 +
!published_status
 +
|Limit the results to only include articles with the given published status ('published' or 'unpublished').
 +
|-
 +
!created_at_min
 +
|Return only the articles created after the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!created_at_max
 +
|Return only the articles created before the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!updated_at_min
 +
|Return only the articles updated after the given date and time. Use the format "2014-12-31 12:00".
 +
|-
 +
!updated_at_max
 +
|Return only the articles updated before the given date and time. Use the format "2014-12-31 12:00".
 +
|}
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
GET /api/blogs/BLOG_ID/articles/count.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{
 +
  "count": 15
 +
}
 +
 
 +
</pre>
 +
 
 +
=== <code>GET /api/blogs/BLOG_ID/articles/ARTICLE_ID.json</code> ===
 +
 
 +
Retrieves a single article by ID.
 +
 
 +
==== Optional Parameters ====
 +
 
 +
{| class="reference"
 +
!fields
 +
|A comma-separated list of fields to return in the response.
 +
|}
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
GET /api/blogs/472/articles/190.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{
 +
  "article": {
 +
    "id": 190,
 +
    "blog_id": 472,
 +
    "title": "Test API blog article",
 +
    "handle": "test-api-blog-article",
 +
    "author": "Bilbo Baggins",
 +
    "body": "This is a test blog article",
 +
    "body_html": "<p>This is a test blog article</p>",
 +
    "created_at": "2016-03-30T17:10:44.992+11:00",
 +
    "updated_at": "2016-03-30T17:10:44.992+11:00",
 +
    "published": true,
 +
    "published_at": "2016-03-30T17:10:44.986+11:00"
 +
  }
 +
}
 +
</pre>
 +
 
 +
=== <code>GET /api/articles/authors.json</code> ===
 +
 
 +
Retrieves all the authors that have contributed to the store blogs.
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
GET /api/articles/authors.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{
 +
  "authors": [
 +
    "Bilbo Baggins",
 +
    "Willy Wonker",
 +
    "System Admin"
 +
  ]
 +
}
 +
</pre>
 +
 
 +
=== <code>POST /api/blogs/BLOG_ID/articles.json</code> ===
 +
 
 +
Add an article to the blog.
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
POST /api/blogs/472/articles.json
 +
 
 +
{
 +
  "article": {
 +
    "title": "My Latest Product Article",
 +
    "author": "Bilbo Baggins",
 +
    "body": "Buy this product. It's great!",
 +
    "published": true
 +
  }
 +
}
 +
 
 +
HTTP/1.1 201 Created
 +
</pre>
 +
 
 +
=== <code>PUT /api/blogs/BLOG_ID/articles/ARTICLE_ID.json</code> ===
 +
 
 +
Updates an article.
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
PUT /api/blogs/472/articles/248.json
 +
 
 +
{
 +
  "article": {
 +
    "id": 248,
 +
    "published": false
 +
  }
 +
}
 +
 
 +
HTTP/1.1 200 OK
 +
</pre>
 +
 
 +
=== <code>DELETE /api/blogs/BLOG_ID/articles/ARTICLE_ID.json</code> ===
 +
 
 +
Deletes an article from a blog.
 +
 
 +
==== Example Request and Response ====
 +
 
 +
<pre>
 +
DELETE /api/blogs/472/articles/248.json
 +
 
 +
HTTP/1.1 200 OK
 +
 
 +
{}
 +
</pre>
  
 
== Further Reference ==
 
== Further Reference ==

Revision as of 13:03, 24 May 2018

An article is a single entry in a blog.

Articles appear in reverse chronological order, with the most recent entry at the top of the blog's page. An article belongs to only one blog.

Article Properties

id 
{ "id" : 191 }

A unique numeric identifier for the article.

blog_id 
{ "blog_id" : 472 }

A unique numeric identifier for the blog that the article belongs to.

title 
{ "title": "My First Article" }

The title of the article.

handle 
{ "handle": "my-first-article" }

A unique, human-friendly string for the article, generated automatically from its title. In online store themes, the Liquid templating language refers to a article by its handle.

author 
{ "author": "Bilbo Baggins" }

The author of the article.

body 
{ "body": "This is a test blog article" }

The text content of the article in Textile markup. This is automatically translated into body_html for display on a browser.

body_html 
{ "body_html": "<p>This is a test blog article</p>" }

The text content of the article, complete with HTML markup.

created_at 
{ "created_at": "2008-07-15T20:00:00-04:00" }

The date and time (ISO 8601 format) when the article was created.

updated_at 
{ "updated_at": "2008-07-16T20:00:00-04:00" }

The date and time (ISO 8601 format) when the article was last updated.

published 
{ "published" : true }

Indicates whether the blog is published and visible to customers.

published_at 
{ "published_at": "2008-07-16T20:00:00-04:00" }

The date and time (ISO 8601 format) when the article was published.

Endpoints

GET /api/blogs/BLOG_ID/articles.json

Retrieve a list of all articles belonging to the blog.

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.
title Limit the results to only include articles with the given title.
handle Limit the results to only include articles with the given handle.
author Limit the results to only include articles written by the given author.
published_status Limit the results to only include articles with the given published status ('published' or 'unpublished').
created_at_min Return only the articles created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the articles created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the articles updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the articles 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.

Example Request and Response

GET /api/blogs/BLOG_ID/articles.json

HTTP/1.1 200 OK

{
  "articles": [
    {
      "id": 190,
      "blog_id": 472,
      "title": "Test API blog article",
      "handle": "test-api-blog-article",
      "author": "Bilbo Baggins",
      "body": "This is a test blog article",
      "body_html": "<p>This is a test blog article</p>",
      "created_at": "2016-03-30T17:10:44.992+11:00",
      "updated_at": "2016-03-30T17:10:44.992+11:00",
      "published": true,
      "published_at": "2016-03-30T17:10:44.986+11:00"
    }, ...
  ]
}

Examples using filters

GET /api/blogs/BLOG_ID/articles.json?fields=id,title

GET /api/blogs/BLOG_ID/articles/count.json

Return a count of the number of articles.

Optional Parameters

since_id Limit the results to only include objects which have an id greater than the given value.
title Limit the results to only include articles with the given title.
handle Limit the results to only include articles with the given handle.
author Limit the results to only include articles written by the given author.
published_status Limit the results to only include articles with the given published status ('published' or 'unpublished').
created_at_min Return only the articles created after the given date and time. Use the format "2014-12-31 12:00".
created_at_max Return only the articles created before the given date and time. Use the format "2014-12-31 12:00".
updated_at_min Return only the articles updated after the given date and time. Use the format "2014-12-31 12:00".
updated_at_max Return only the articles updated before the given date and time. Use the format "2014-12-31 12:00".

Example Request and Response

GET /api/blogs/BLOG_ID/articles/count.json

HTTP/1.1 200 OK

{
  "count": 15
}

GET /api/blogs/BLOG_ID/articles/ARTICLE_ID.json

Retrieves a single article by ID.

Optional Parameters

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

Example Request and Response

GET /api/blogs/472/articles/190.json

HTTP/1.1 200 OK

{
  "article": {
    "id": 190,
    "blog_id": 472,
    "title": "Test API blog article",
    "handle": "test-api-blog-article",
    "author": "Bilbo Baggins",
    "body": "This is a test blog article",
    "body_html": "<p>This is a test blog article</p>",
    "created_at": "2016-03-30T17:10:44.992+11:00",
    "updated_at": "2016-03-30T17:10:44.992+11:00",
    "published": true,
    "published_at": "2016-03-30T17:10:44.986+11:00"
  }
}

GET /api/articles/authors.json

Retrieves all the authors that have contributed to the store blogs.

Example Request and Response

GET /api/articles/authors.json

HTTP/1.1 200 OK

{
  "authors": [
    "Bilbo Baggins",
    "Willy Wonker",
    "System Admin"
  ]
}

POST /api/blogs/BLOG_ID/articles.json

Add an article to the blog.

Example Request and Response

POST /api/blogs/472/articles.json

{
  "article": {
    "title": "My Latest Product Article",
    "author": "Bilbo Baggins",
    "body": "Buy this product. It's great!",
    "published": true
  }
}

HTTP/1.1 201 Created

PUT /api/blogs/BLOG_ID/articles/ARTICLE_ID.json

Updates an article.

Example Request and Response

PUT /api/blogs/472/articles/248.json

{
  "article": {
    "id": 248,
    "published": false
  }
}

HTTP/1.1 200 OK

DELETE /api/blogs/BLOG_ID/articles/ARTICLE_ID.json

Deletes an article from a blog.

Example Request and Response

DELETE /api/blogs/472/articles/248.json

HTTP/1.1 200 OK

{}

Further Reference

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