Class: Forem::Article

Inherits:
APIResource show all
Extended by:
Forem::APIOperations::Create, Forem::APIOperations::List, Forem::APIOperations::Retrieve, Forem::APIOperations::Update
Includes:
Forem::APIOperations::Save
Defined in:
lib/forem/resources/article.rb

Overview

Represents a Forem article (blog post).

Articles are the core content type on Forem. They support full CRUD operations plus several custom endpoints for filtering by auth state, latest publication order, and full-text search.

Available operations (via mixins):

- +List+   — GET /api/articles
- +Create+ — POST /api/articles
- +Retrieve+ — GET /api/articles/:id
- +Update+ — PUT /api/articles/:id
- +Save+   — instance-level save (create or update)

List Parameters

When calling Article.list, the following query parameters are supported:

  • tag (String) — Filter by tag; can combine with top
  • tags (String) — Comma-separated tags; returns articles with ANY of these
  • tags_exclude (String) — Comma-separated tags to exclude
  • username (String) — Filter by user or organization username
  • state (String) — One of: "fresh", "rising", "all". Note: state=all only works combined with username and returns up to 1000 items
  • top (Integer) — Most popular articles in the last N days; can combine with tag
  • collection_id (Integer) — Articles in a specific collection, ordered by publication date
  • page (Integer) — Page number (default: 1)
  • per_page (Integer) — Items per page (default: 30, max: 1000)

Create Parameters

When calling Article.create, wrap all fields under the :article key:

Examples:

List published articles

articles = client.articles.list(per_page: 10, tag: "ruby")
articles.data.each { |a| puts a.title }

Create a new article

article = client.articles.create(
  article: { title: "Hello World", body_markdown: "# Hello", published: false }
)

Retrieve a single article by ID

article = client.articles.retrieve(12345)
puts article.title

See Also:

Constant Summary collapse

OBJECT_NAME = 
"article"
RESOURCE_PATH = 
"/api/articles"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Forem::APIOperations::Create

create

Methods included from Forem::APIOperations::List

list

Methods included from Forem::APIOperations::Retrieve

retrieve

Methods included from Forem::APIOperations::Update

update

Methods included from Forem::APIOperations::Save

#save

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from Forem::APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Class Method Details

.latest(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return the most recently published articles ordered by publication date.

Sends a GET request to /api/articles/latest.

Examples:

latest = client.articles.latest(per_page: 5)
latest.each { |a| puts "#{a.published_at}: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



188
189
190
 
# File 'lib/forem/resources/article.rb', line 188

def self.latest(params = {}, opts = {})
  paginated_list("/api/articles/latest", params, opts)
end

.me(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return articles authored by the authenticated user (all statuses).

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me.

Examples:

my_articles = client.articles.me(per_page: 5)
my_articles.each { |a| puts "#{a.id}: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



107
108
109
 
# File 'lib/forem/resources/article.rb', line 107

def self.me(params = {}, opts = {})
  paginated_list("/api/articles/me", params, opts)
end

.me_all(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return all articles authored by the authenticated user regardless of status.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/all.

Examples:

all = client.articles.me_all
all.auto_paging_each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



170
171
172
 
# File 'lib/forem/resources/article.rb', line 170

def self.me_all(params = {}, opts = {})
  paginated_list("/api/articles/me/all", params, opts)
end

.me_published(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return published articles authored by the authenticated user.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/published.

Examples:

published = client.articles.me_published(per_page: 20)
published.each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



128
129
130
 
# File 'lib/forem/resources/article.rb', line 128

def self.me_published(params = {}, opts = {})
  paginated_list("/api/articles/me/published", params, opts)
end

.me_unpublished(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return unpublished (draft) articles authored by the authenticated user.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/unpublished.

Examples:

drafts = client.articles.me_unpublished
drafts.each { |a| puts "Draft: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



149
150
151
 
# File 'lib/forem/resources/article.rb', line 149

def self.me_unpublished(params = {}, opts = {})
  paginated_list("/api/articles/me/unpublished", params, opts)
end

.retrieve_by_path(username, slug, opts = {}) ⇒ Forem::Article

Retrieve a single article by the author's username and the article's slug.

Sends a GET request to /api/articles/:username/:slug.

Examples:

article = client.articles.retrieve_by_path("ben", "my-first-post")
puts article.title

Parameters:

  • username (String) —

    the author's Forem username

  • slug (String) —

    the article slug (the URL-friendly title segment)

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



250
251
252
253
254
 
# File 'lib/forem/resources/article.rb', line 250

def self.retrieve_by_path(username, slug, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/articles/#{CGI.escape(username)}/#{CGI.escape(slug)}", {}, opts)
  construct_from(resp.parsed_body, requestor: requestor)
end

.search(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Search published articles by keyword.

Sends a GET request to /api/articles/search.

Examples:

results = client.articles.search(q: "ruby on rails")
results.each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :q (String) —

    search query string

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



207
208
209
 
# File 'lib/forem/resources/article.rb', line 207

def self.search(params = {}, opts = {})
  paginated_list("/api/articles/search", params, opts)
end

.semantic_search(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Semantically search published articles using Forem's embeddings-based search.

Unlike search (keyword matching), this endpoint finds articles whose meaning is close to the query text, using vector similarity. Requires authentication.

Sends a GET request to /api/articles/semantic_search.

Examples:

results = client.articles.semantic_search(q: "how to deploy rails apps")
results.each { |a| puts "#{a.title} (#{a.similarity})" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :q (String) —

    the search query text (required)

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 10, max: 50)

  • :threshold (Float) —

    optional cosine distance threshold (0.0-2.0) used to filter out weakly-related results

Returns:

  • (Forem::ListObject<Forem::Article>) —

    paginated list of articles matching the query, ordered by relevance. Each article additionally exposes distance (cosine distance) and similarity (1 - distance) attributes.

See Also:



234
235
236
 
# File 'lib/forem/resources/article.rb', line 234

def self.semantic_search(params = {}, opts = {})
  paginated_list("/api/articles/semantic_search", params, opts)
end

Instance Method Details

#unpublish(opts = {}) ⇒ ForemResponse

Unpublish this article, reverting it to draft status.

Marks the article as draft. Keeps content, deletes notifications, preserves comments. Requires admin or moderator role.

Sends a PUT request to /api/articles/:id/unpublish.

Examples:

article = client.articles.retrieve(42)
article.unpublish

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



86
87
88
 
# File 'lib/forem/resources/article.rb', line 86

def unpublish(opts = {})
  request(:put, "#{resource_url}/unpublish", {}, opts)
end