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.

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: [], objects: []) ⇒ Package

Returns a new instance of Package.



18
19
20
21
22
23
24
25
26
27
28
29
30
 
# 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: [], objects: [])
  @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] }
  @objects = objects.to_h { |o| [o.name, o] }
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) 


61
62
63
 
# File 'lib/web_function/package.rb', line 61

def base_url
  @base_url
end

#docs ⇒ String (readonly)

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

Returns:

  • (String) 


88
89
90
 
# File 'lib/web_function/package.rb', line 88

def docs
  @docs
end

#name ⇒ String? (readonly)

The name of the package.

Returns:

  • (String, nil) 


74
75
76
 
# File 'lib/web_function/package.rb', line 74

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) 


68
69
70
 
# File 'lib/web_function/package.rb', line 68

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) 


82
83
84
 
# File 'lib/web_function/package.rb', line 82

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


96
97
98
 
# File 'lib/web_function/package.rb', line 96

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



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

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"]),
    objects: ObjectSchema.from_array(package["objects"]),
  )
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.



126
127
128
 
# File 'lib/web_function/package.rb', line 126

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

#endpoints ⇒ Array<Endpoint>

The endpoints declared by this package.

Returns:



115
116
117
 
# File 'lib/web_function/package.rb', line 115

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:



145
146
147
 
# File 'lib/web_function/package.rb', line 145

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:



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

def errors
  @errors.values
end

#object(name, context:) ⇒ ObjectSchema?

Looks up a single object definition by name, resolved for the given context.

An object. reference appears in either an argument or attribute context, which determines which set of members applies. The context selects the member set that is relevant; an object that does not define members for the requested context is treated as absent and nil is returned.

Parameters:

  • name (String, Symbol) —

    The name of the object to look up.

  • context (Symbol) —

    The context the object is referenced in. One of ObjectSchema::CONTEXTS (:arguments or :attributes).

Returns:

  • (ObjectSchema, nil) —

    The matching object, or nil if none is found or it defines no members for the given context.

Raises:



173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/web_function/package.rb', line 173

def object(name, context:)
  object = @objects[name.to_s]

  unless object
    return
  end

  if object.properties(context).empty?
    return
  end

  object
end

#objects ⇒ Array<ObjectSchema>

The named object definitions declared by this package. Each can be referenced as a refined object type (object.<name>) anywhere a type is expected.

Returns:



154
155
156
 
# File 'lib/web_function/package.rb', line 154

def objects
  @objects.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:



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

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) 


192
193
194
 
# File 'lib/web_function/package.rb', line 192

def versioned?
  flag?("versioned")
end