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: 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: [], hints: [], 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
38
 
# File 'lib/web_function/endpoint.rb', line 28

def initialize(name:, returns: [], hints: [], flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: [])
  @name = name
  @returns = returns
  @hints = hints
  @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:



100
101
102
 
# File 'lib/web_function/endpoint.rb', line 100

def client
  @client
end

#docs ⇒ String (readonly)

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

Returns:

  • (String) 


143
144
145
 
# File 'lib/web_function/endpoint.rb', line 143

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) 


137
138
139
 
# File 'lib/web_function/endpoint.rb', line 137

def group
  @group
end

#hints ⇒ Array<String> (readonly)

Hints for the endpoint’s return value. Each hint’s base JSON type matches one of the endpoint’s #returns types, and at most one hint is supplied per base JSON type. See the [hints section] on the Web Function website for the complete list of allowed hints.

[1]: webfunction.org/package#hints

Returns:

  • (Array<String>) 


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

def hints
  @hints
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) 


107
108
109
 
# File 'lib/web_function/endpoint.rb', line 107

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


120
121
122
 
# File 'lib/web_function/endpoint.rb', line 120

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



88
89
90
91
92
 
# File 'lib/web_function/endpoint.rb', line 88

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



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

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

  unless endpoint["name"]
    return
  end

  new(
    name: endpoint["name"],
    returns: Utils.normalize_array_of_strings(endpoint["returns"]),
    hints: Utils.normalize_array_of_strings(endpoint["hints"]),
    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



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

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.



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

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:



202
203
204
 
# File 'lib/web_function/endpoint.rb', line 202

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.



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

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:



184
185
186
 
# File 'lib/web_function/endpoint.rb', line 184

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) 


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

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.



153
154
155
156
157
158
159
 
# File 'lib/web_function/endpoint.rb', line 153

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) 


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

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:

  • (DocumentedError, nil) —

    The matching error, or ‘nil` if none is found.



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

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:



166
167
168
 
# File 'lib/web_function/endpoint.rb', line 166

def errors
  @errors.values
end

#paginated? ⇒ Boolean

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

Returns:

  • (Boolean) 


237
238
239
 
# File 'lib/web_function/endpoint.rb', line 237

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) 


247
248
249
 
# File 'lib/web_function/endpoint.rb', line 247

def private?
  flag?("private")
end