Class: WebFunction::Endpoint

Inherits:
Object
  • Object
show all
Includes:
Flaggable
Defined in:
lib/web_function/endpoint.rb

Overview

Represents an endpoint as described in a Web Function package.

An endpoint defines an operation that can be performed via a Web Function API. Endpoints declare their name, documentation, arguments (inputs), attributes (outputs), and the possible errors that may occur when invoking them.

Endpoints are described as objects in each package under the "endpoints" key. For more information, see:

This class provides methods for accessing endpoint metadata (name, docs, arguments, attributes, errors) and supports invocation via HTTP.

Typical tasks include:

  • Querying endpoint name or documentation
  • Enumerating the arguments or attributes definitions
  • Invoking the endpoint through HTTP using required inputs

See: https://webfunction.org/endpoint for more details on endpoint structure and contract.

Instance Attribute Summary collapse

Attributes included from Flaggable

#flags

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Flaggable

#flag?

Constructor Details

#initialize(name:, returns:, flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: []) ⇒ Endpoint

Returns a new instance of Endpoint.



28
29
30
31
32
33
34
35
36
37
 
# File 'lib/web_function/endpoint.rb', line 28

def initialize(name:, returns:, flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: [])
  @name = name
  @returns = Type.parse(returns)
  @flags = flags
  @group = group
  @docs = docs
  @arguments = arguments.to_h { |a| [a.name, a] }
  @attributes = attributes.to_h { |a| [a.name, a] }
  @errors = errors.to_h { |e| [e.code, e] }
end

Instance Attribute Details

#client ⇒ Client?

The Client used to invoke this endpoint. It is assigned when the endpoint is loaded from a package and is required by #call.

Returns:



102
103
104
 
# File 'lib/web_function/endpoint.rb', line 102

def client
  @client
end

#docs ⇒ String (readonly)

Documentation for the endpoint. It must be formatted as markdown.

Returns:

  • (String) 


135
136
137
 
# File 'lib/web_function/endpoint.rb', line 135

def docs
  @docs
end

#group ⇒ String? (readonly)

A name used to categorize or group similar endpoints together. This should be used by documentation tools to organize related endpoints.

Returns:

  • (String, nil) 


129
130
131
 
# File 'lib/web_function/endpoint.rb', line 129

def group
  @group
end

#name ⇒ String (readonly)

The suffix for the endpoint URL, appended to the package's base URL to form the full endpoint URL. Endpoint names are unique within a package; overloading (two endpoints sharing the same name) is not permitted.

Returns:

  • (String) 


109
110
111
 
# File 'lib/web_function/endpoint.rb', line 109

def name
  @name
end

#returns ⇒ Array<String> (readonly)

The JSON type(s) returned by the endpoint. A non-empty array whose entries are each one of:

  • object
  • array
  • string
  • number
  • boolean
  • null

Returns:

  • (Array<String>) 


122
123
124
 
# File 'lib/web_function/endpoint.rb', line 122

def returns
  @returns
end

Class Method Details

.from_array(endpoints) ⇒ Array<Endpoint>

Creates a new Endpoint from an array of hashes. Uses from_hash under the hood.

Parameters:

  • endpoints (Array<Hash>) —

    The endpoint array of hashes

Returns:

  • (Array<Endpoint>) —

    A new array of Endpoint instances



90
91
92
93
94
 
# File 'lib/web_function/endpoint.rb', line 90

def from_array(endpoints)
  Utils.normalize_array endpoints do |endpoint|
    from_hash(endpoint)
  end
end

.from_hash(endpoint) ⇒ Endpoint

Creates a new Endpoint from a hash.

Parameters:

  • endpoint (Hash) —

    The endpoint hash

Returns:

  • (Endpoint) —

    A new Endpoint instance



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/web_function/endpoint.rb', line 59

def from_hash(endpoint)
  unless endpoint.is_a?(Hash)
    return
  end

  unless endpoint["name"]
    return
  end

  unless endpoint["returns"]
    return
  end

  new(
    name: endpoint["name"],
    returns: endpoint["returns"],
    flags: Utils.normalize_array_of_strings(endpoint["flags"]),
    group: endpoint["group"],
    docs: endpoint["docs"].to_s,
    arguments: Argument.from_array(endpoint["arguments"]),
    attributes: Attribute.from_array(endpoint["attributes"]),
    errors: DocumentedError.from_array(endpoint["errors"]),
  )
end

.invoke(url, bearer_auth: nil, version: nil, args: {}) ⇒ Object

Invokes an endpoint through HTTP using the given URL, bearer authentication, version, and arguments.

Parameters:

  • url (String) —

    The URL of the endpoint to invoke

  • bearer_auth (String) (defaults to: nil) —

    The bearer authentication token

  • version (String) (defaults to: nil) —

    The API version to use

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

    The arguments to send to the endpoint

Returns:

  • (Object) —

    The response returned by the endpoint



49
50
51
 
# File 'lib/web_function/endpoint.rb', line 49

def invoke(url, bearer_auth: nil, version: nil, args: {})
  Request.execute(url, bearer_auth: bearer_auth, version: version, args: args)
end

Instance Method Details

#argument(name) ⇒ Argument?

Looks up a single argument by name.

Parameters:

  • name (String, Symbol) —

    The name of the argument to look up.

Returns:

  • (Argument, nil) —

    The matching argument, or nil if none is found.



204
205
206
 
# File 'lib/web_function/endpoint.rb', line 204

def argument(name)
  @arguments[name.to_s]
end

#arguments ⇒ Array<Argument>

The arguments required by the endpoint. The array is empty when the endpoint requires no arguments.

Returns:



194
195
196
 
# File 'lib/web_function/endpoint.rb', line 194

def arguments
  @arguments.values
end

#attribute(name) ⇒ Attribute?

Looks up a single returned attribute by name.

Parameters:

  • name (String, Symbol) —

    The name of the attribute to look up.

Returns:

  • (Attribute, nil) —

    The matching attribute, or nil if none is found.



186
187
188
 
# File 'lib/web_function/endpoint.rb', line 186

def attribute(name)
  @attributes[name.to_s]
end

#attributes ⇒ Array<Attribute>

The attributes of the object returned by the endpoint. Relevant when the endpoint returns an object.

Returns:



176
177
178
 
# File 'lib/web_function/endpoint.rb', line 176

def attributes
  @attributes.values
end

#bearer_auth? ⇒ Boolean

Whether the endpoint requires authentication via a bearer token, i.e. whether it declares the bearer_auth flag.

Returns:

  • (Boolean) 


212
213
214
 
# File 'lib/web_function/endpoint.rb', line 212

def bearer_auth?
  flag?("bearer_auth")
end

#call(args = {}) ⇒ Object

Invokes the endpoint through its assigned #client, passing the given arguments.

Parameters:

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

    The arguments to send to the endpoint.

Returns:

  • (Object) —

    The decoded response returned by the endpoint.

Raises:

  • (RuntimeError) —

    If no client has been assigned to the endpoint.



145
146
147
148
149
150
151
 
# File 'lib/web_function/endpoint.rb', line 145

def call(args = {})
  unless client
    raise "Client must be set to invoke an endpoint"
  end

  client.call(name, args)
end

#capture_bearer? ⇒ Boolean

Whether the endpoint returns a bearer token in its response, i.e. whether it declares the capture_bearer flag. See the authentication specification for more information.

Returns:

  • (Boolean) 


221
222
223
 
# File 'lib/web_function/endpoint.rb', line 221

def capture_bearer?
  flag?("capture_bearer")
end

#error(code) ⇒ DocumentedError?

Looks up a single endpoint error by its machine-readable code.

Parameters:

  • code (String, Symbol) —

    The error code to look up.

Returns:



168
169
170
 
# File 'lib/web_function/endpoint.rb', line 168

def error(code)
  @errors[code.to_s]
end

#errors ⇒ Array<DocumentedError>

The list of errors specific to this endpoint. Clients SHOULD only refer to this list if the endpoint uses the error_triple flag. See the error specification for more information.

Returns:



158
159
160
 
# File 'lib/web_function/endpoint.rb', line 158

def errors
  @errors.values
end

#paginated? ⇒ Boolean

Whether the endpoint supports pagination, i.e. whether it declares the paginated flag.

Returns:

  • (Boolean) 


229
230
231
 
# File 'lib/web_function/endpoint.rb', line 229

def paginated?
  flag?("paginated")
end

#private? ⇒ Boolean

Whether the endpoint is intended for internal use and is not part of the public API, i.e. whether it declares the private flag. Documentation tooling SHOULD omit endpoints with this flag from generated or published documentation.

Returns:

  • (Boolean) 


239
240
241
 
# File 'lib/web_function/endpoint.rb', line 239

def private?
  flag?("private")
end