View source for API Article

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 ==

* [[An Introduction to the Spiffy Stores API]]
* [[Creating Private API Keys]]
* [[Using the API]]
* [[API Reference]]