Class: Forem::APIResource

Inherits:
ForemObject show all
Defined in:
lib/forem/api_resource.rb

Overview

Base class for all Forem API resource objects (articles, users, etc.).

APIResource extends ForemObject with the concepts of a canonical resource path and the ability to refresh an instance from the API. Concrete resource classes must define a RESOURCE_PATH constant (e.g. "/api/articles").

Resource classes mix in Forem::APIOperations::Request so that both the class and its instances can issue authenticated HTTP requests. Class methods require an explicit :requestor option (normally injected by a Client via its service objects); instance methods fall back to the requestor stored on the object at construction time.

Examples:

Defining a resource subclass

class Forem::Article < Forem::APIResource
  RESOURCE_PATH = "/api/articles"
  extend APIOperations::List
  extend APIOperations::Retrieve
end

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

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

.resource_path ⇒ String

Return the API collection path for this resource class.

Delegates to the RESOURCE_PATH constant that every concrete subclass must define.

Examples:

Forem::Article.resource_path  #=> "/api/articles"

Returns:

  • (String) —

    the collection path, e.g. "/api/articles".

Raises:

  • (NameError) —

    if the subclass has not defined RESOURCE_PATH.



32
33
34
 
# File 'lib/forem/api_resource.rb', line 32

def self.resource_path
  self::RESOURCE_PATH
end

Instance Method Details

#refresh(opts = {}) ⇒ self

Reload this resource instance from the API, replacing all attributes with the latest server data.

Examples:

article = client.articles.retrieve(42)
# ... time passes ...
article.refresh   #=> same article object with updated attributes

Parameters:

Options Hash (opts):

  • :api_key (String) —

    override the API key for this request.

  • :requestor (APIRequestor) —

    a custom requestor to use.

Returns:

  • (self) —

    the same instance, now populated with refreshed data.

Raises:

See Also:



70
71
72
73
74
75
 
# File 'lib/forem/api_resource.rb', line 70

def refresh(opts = {})
  resp = request(:get, resource_url, {}, opts)
  @values = {}
  send(:update_attributes, resp.parsed_body)
  self
end

#resource_url ⇒ String

Return the API path for this specific resource instance.

Combines resource_path with the instance's id attribute.

Examples:

article.resource_url  #=> "/api/articles/42"

Returns:

  • (String) —

    the instance path, e.g. "/api/articles/42".

Raises:

  • (InvalidRequestError) —

    if the instance does not have an id attribute (i.e. the object was not constructed from a full API response).



47
48
49
50
51
 
# File 'lib/forem/api_resource.rb', line 47

def resource_url
  id = self["id"]
  raise InvalidRequestError.new("Could not determine resource ID") unless id
  "#{self.class.resource_path}/#{id}"
end