class Apigen::Rest::Endpoint

Endpoint is a definition of a specific endpoint in the API, e.g. /users with GET method.

Constants

PATH_PARAMETER_REGEX

Attributes

outputs[R]
path_parameters[R]
query_parameters[R]

Public Class Methods

new(name) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 19
def initialize(name)
  @name = name
  @method = nil
  @path = nil
  @path_parameters = Apigen::ObjectType.new
  @query_parameters = Apigen::ObjectType.new
  @input = nil
  @outputs = []
  @description = nil
end

Public Instance Methods

input(&block) click to toggle source

Declares the input type of an endpoint.

# File lib/apigen/rest/endpoint.rb, line 63
def input(&block)
  return @input unless block_given?
  @input = Input.new
  @input.instance_eval(&block)
end
method(method = nil) click to toggle source

Declares the HTTP method.

# File lib/apigen/rest/endpoint.rb, line 32
def method(method = nil)
  return @method unless method
  case method
  when :get, :post, :put, :delete
    @method = method
  else
    raise "Unknown HTTP method :#{method}."
  end
end
output(name, &block) click to toggle source

Declares the output of an endpoint for a given status code.

# File lib/apigen/rest/endpoint.rb, line 71
def output(name, &block)
  raise "Endpoint :#{@name} declares the output :#{name} twice." if @outputs.find { |o| o.name == name }
  output = Output.new name
  @outputs << output
  raise 'You must pass a block when calling `output`.' unless block_given?
  output.instance_eval(&block)
  output
end
path(path = nil, &block) click to toggle source

Declares the endpoint path relative to the host.

# File lib/apigen/rest/endpoint.rb, line 44
def path(path = nil, &block)
  return @path unless path
  @path = path
  if PATH_PARAMETER_REGEX.match path
    set_path_parameters(path, &block)
  elsif block_given?
    raise 'A path block was provided but no URL parameter was found.'
  end
end
query(&block) click to toggle source

Declares query parameters.

# File lib/apigen/rest/endpoint.rb, line 56
def query(&block)
  raise 'You must pass a block when calling `query`.' unless block_given?
  @query_parameters.instance_eval(&block)
end
to_s() click to toggle source
# File lib/apigen/rest/endpoint.rb, line 97
def to_s
  repr = "#{@name}:"
  input_str = @input.to_s
  repr += " #{input_str}" unless input_str.empty?
  @outputs.each do |output|
    repr += "\n-> #{output}"
  end
  repr += "\n"
  repr
end
update_output(name, &block) click to toggle source

Updates an already-declared output.

# File lib/apigen/rest/endpoint.rb, line 82
def update_output(name, &block)
  output = @outputs.find { |o| o.name == name }
  raise "Endpoint :#{@name} never declares the output :#{name} so it cannot be updated." unless output
  raise 'You must pass a block when calling `update_output`.' unless block_given?
  output.instance_eval(&block)
  output
end
validate(model_registry) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 90
def validate(model_registry)
  validate_properties
  validate_input(model_registry)
  validate_path_parameters(model_registry)
  validate_outputs(model_registry)
end

Private Instance Methods

ensure_defined_parameters_all_appear_in_path(parameters_found_in_path) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 124
def ensure_defined_parameters_all_appear_in_path(parameters_found_in_path)
  @path_parameters.properties.each do |parameter, _type|
    raise "Parameter :#{parameter} does not appear in path #{@path}." unless parameters_found_in_path.include? parameter
  end
end
ensure_parameters_found_in_path_all_defined(parameters_found_in_path) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 118
def ensure_parameters_found_in_path_all_defined(parameters_found_in_path)
  parameters_found_in_path.each do |parameter|
    raise "Path parameter :#{parameter} in path #{@path} is not defined." unless @path_parameters.properties.key? parameter
  end
end
set_path_parameters(path, &block) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 110
def set_path_parameters(path, &block)
  block = {} unless block_given?
  @path_parameters.instance_eval(&block)
  parameters_found_in_path = path.scan(PATH_PARAMETER_REGEX).map { |parameter, _| parameter.to_sym }
  ensure_parameters_found_in_path_all_defined(parameters_found_in_path)
  ensure_defined_parameters_all_appear_in_path(parameters_found_in_path)
end
validate_forbidden_input() click to toggle source
# File lib/apigen/rest/endpoint.rb, line 155
def validate_forbidden_input
  raise "Endpoint :#{@name} with method #{@method.to_s.upcase} cannot accept an input payload." if @input
end
validate_input(model_registry) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 141
def validate_input(model_registry)
  case @method
  when :put, :post
    validate_required_input(model_registry)
  when :get, :delete
    validate_forbidden_input
  end
end
validate_outputs(model_registry) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 163
def validate_outputs(model_registry)
  raise "Endpoint :#{@name} does not declare any outputs" if @outputs.empty?
  @outputs.each do |output|
    output.validate model_registry
  end
end
validate_path_parameters(model_registry) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 159
def validate_path_parameters(model_registry)
  @path_parameters.validate model_registry
end
validate_properties() click to toggle source
# File lib/apigen/rest/endpoint.rb, line 130
def validate_properties
  error = if !@name
            'One of the endpoints is missing a name.'
          elsif !@method
            "Use `method :get/post/put/delete` to set an HTTP method for :#{@name}."
          elsif !@path
            "Use `path \"/some/path\"` to assign a path to :#{@name}."
          end
  raise error unless error.nil?
end
validate_required_input(model_registry) click to toggle source
# File lib/apigen/rest/endpoint.rb, line 150
def validate_required_input(model_registry)
  raise "Use `input { type :typename }` to assign an input type to :#{@name}." unless @input
  @input.validate(model_registry)
end