Class: WebFunction::Package

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

Overview

Organize, document, and validate endpoints. A package facilitates Endpoint discovery and integration by providing standardized metadata about them.

A package bundles a base URL together with the endpoints it exposes, as well as optional metadata such as a name, version information, top-level documentation, and a list of common errors.

See the [package specification] on the Web Function website for the full description of every recognized key and its constraints.

[0]: webfunction.org/package

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(base_url:, pipeline_url: nil, name: nil, version: nil, docs: nil, flags: [], versions: [], endpoints: [], errors: []) ⇒ Package

Returns a new instance of Package.



18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/web_function/package.rb', line 18

def initialize(base_url:, pipeline_url: nil, name: nil, version: nil, docs: nil, flags: [], versions: [],
               endpoints: [], errors: [])
  @base_url = base_url
  @pipeline_url = pipeline_url
  @name = name
  @version = version
  @docs = docs.to_s
  @flags = flags
  @versions = versions
  @endpoints = endpoints.to_h { |e| [e.name, e] }
  @errors = errors.to_h { |e| [e.code, e] }
end

Instance Attribute Details

#base_url ⇒ String (readonly)

The base URL for the package. Endpoint URLs are formed by joining this base URL with each endpoint’s name.

This is required for the package to be valid and MUST use the HTTP or HTTPS scheme.

Returns:

  • (String) 


59
60
61
 
# File 'lib/web_function/package.rb', line 59

def base_url
  @base_url
end

#docs ⇒ String (readonly)

Top-level documentation for the package. It must be formatted as markdown.

Returns:

  • (String) 


86
87
88
 
# File 'lib/web_function/package.rb', line 86

def docs
  @docs
end

#name ⇒ String? (readonly)

The name of the package.

Returns:

  • (String, nil) 


72
73
74
 
# File 'lib/web_function/package.rb', line 72

def name
  @name
end

#pipeline_url ⇒ String? (readonly)

A function pipelining URL used to batch several endpoint invocations into a single request. See the pipelining specification for more information.

Returns:

  • (String, nil) 


66
67
68
 
# File 'lib/web_function/package.rb', line 66

def pipeline_url
  @pipeline_url
end

#version ⇒ String? (readonly)

The version that this package describes. An opaque string.

This MUST be present when the ‘versioned` flag is set. See the versioning specification for more information.

Returns:

  • (String, nil) 


80
81
82
 
# File 'lib/web_function/package.rb', line 80

def version
  @version
end

#versions ⇒ Array<String> (readonly)

The versions that are available. Each entry is an opaque string.

This MUST be present when the ‘versioned` flag is set. See the versioning specification for more information.

Returns:

  • (Array<String>) 


94
95
96
 
# File 'lib/web_function/package.rb', line 94

def versions
  @versions
end

Class Method Details

.from_hash(package) ⇒ Package

Instantiate a new Package from a hash.

Parameters:

  • package (Hash) —

    The package hash

Returns:

  • (Package) —

    A new Package instance



38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/web_function/package.rb', line 38

def from_hash(package)
  new(
    base_url: package["base_url"],
    pipeline_url: package["pipeline_url"],
    name: package["name"],
    version: package["version"],
    docs: package["docs"],
    flags: Utils.normalize_array_of_strings(package["flags"]),
    versions: Utils.normalize_array_of_strings(package["versions"]),
    endpoints: Endpoint.from_array(package["endpoints"]),
    errors: DocumentedError.from_array(package["errors"]),
  )
end

Instance Method Details

#endpoint(name) ⇒ Endpoint?

Looks up a single endpoint by name. Underscores in the given name are converted to hyphens so that Ruby-style names (e.g. ‘:find_user_by`) match the hyphenated endpoint names used in packages (e.g. `find-user-by`).

Parameters:

  • name (String, Symbol) —

    The name of the endpoint to look up.

Returns:

  • (Endpoint, nil) —

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



124
125
126
 
# File 'lib/web_function/package.rb', line 124

def endpoint(name)
  @endpoints[name.to_s.gsub("_", "-")]
end

#endpoints ⇒ Array<Endpoint>

The endpoints declared by this package.

Returns:



113
114
115
 
# File 'lib/web_function/package.rb', line 113

def endpoints
  @endpoints.values
end

#error(code) ⇒ DocumentedError?

Looks up a single common 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.



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

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

#errors ⇒ Array<DocumentedError>

The list of common errors that can be returned by any endpoint in this package. Only refer to this list if an endpoint uses the ‘error_triple` flag. See the error specification for more information.

Returns:



133
134
135
 
# File 'lib/web_function/package.rb', line 133

def errors
  @errors.values
end

#pipeline ⇒ Pipeline?

The WebFunction::Pipeline for this package, built from #pipeline_url, or ‘nil` when the package does not declare a pipeline URL.

Returns:



101
102
103
104
105
106
107
 
# File 'lib/web_function/package.rb', line 101

def pipeline
  unless pipeline_url
    return
  end

  Pipeline.new(pipeline_url)
end

#versioned? ⇒ Boolean

Whether the package is versioned, i.e. whether it declares the ‘versioned` flag. A versioned package is selected using the `Api-Version` header.

Returns:

  • (Boolean) 


152
153
154
 
# File 'lib/web_function/package.rb', line 152

def versioned?
  flag?("versioned")
end