Module: X::Resources::Finders

Included in:
Community, DirectMessage, List, BatchFinders
Defined in:
x-resources/lib/x/resources/finders.rb

Overview

Class methods that look resources up one at a time, extended into each resource class the API can look up

A resource the API offers no lookup of, such as a poll or a place, does not extend it, and so answers none of its methods, rather than answer them only to raise. BatchFinders includes it for a resource the API can also look up many at a time.

Internal to x-resources: the methods it gives a resource class, such as X::Post.find, are public API, but the module is only how they are shared, and which classes extend or include it can change within 1.x.

Instance Method Summary collapse

Instance Method Details

#find(id, client:, **params) {|problem| ... } ⇒ Resource?

Look up a resource by identifier

Examples:

Look up a post by identifier

X::Post.find(1234567890, client: client)

Parameters:

  • id (String, Integer, Resource) —

    the identifier, or a resource of this class

  • client (Object) —

    the client used to make the request

  • params (Hash) —

    query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Yield Parameters:

  • problem (Problem) —

    each problem the API reported, such as a resource that was not found

Returns:

  • (Resource, nil) —

    the resource or nil if it was not found, whether the API answers 200 with no data or a 404 that reports the resource as not found

Raises:

  • (ArgumentError) —

    if the identifier is not one, or is a resource of another class, before a request

  • (X::NotFound) —

    if the API answers any other 404, such as one from a client pointed at the wrong host or API version



35
 
# File 'x-resources/lib/x/resources/finders.rb', line 35

def find(id, client:, **params, &) = locate("#{endpoint!}/#{Utils.id_of(id, self)}", client:, **params, &)

#find!(id, client:, **params) ⇒ Resource

Look up a resource by identifier, which must exist

The error it raises names the identifier looked up, whether the identifier or a resource was given. Its cause is the X::NotFound of a lookup the API answered with a 404 that reports the resource as not found.

Examples:

Look up a post by identifier

X::Post.find!(1234567890, client: client)

Parameters:

  • id (String, Integer, Resource) —

    the identifier, or a resource of this class

  • client (Object) —

    the client used to make the request

  • params (Hash) —

    query parameters merged over the default parameters; one that overrides a default field or expansion parameter to leave some out builds resources that are not hydrated, so hydrate fetches the rest

Returns:

Raises:

  • (ArgumentError) —

    if the identifier is not one, or is a resource of another class, before a request

  • (MissingResource) —

    if the resource was not found, whether the API answers 200 with no data or a 404 that reports the resource as not found

  • (X::NotFound) —

    if the API answers any other 404, such as one from a client pointed at the wrong host or API version



55
56
57
 
# File 'x-resources/lib/x/resources/finders.rb', line 55

def find!(id, client:, **params)
  locate!("#{endpoint!}/#{Utils.id_of(id, self)}", Utils.id_from(id, self), client:, **params)
end