Class: WSDSL

Inherits:
Object
  • Object
show all
Defined in:
lib/wsdsl.rb,
lib/params.rb,
lib/response.rb,
lib/documentation.rb,
lib/response_exceptions.rb

Overview

WSDSL offers a web service DSL to define web services, their params, http verbs, formats expected as well as the documentation for all these aspects of a web service.

This DSL is only meant to describe a web service and isn’t meant to cover any type of implementation details. It is meant to be framework/tool agnostic.

However, tools can be built around the Web Service DSL data structure to extract documentation, generate routing information, verify that an incoming request is valid, generate automated tests…

WSDSL
  |
  |__ service options (name, url, SSL, auth required formats, verbs, controller name, action, version, extra)
  |__ defined_params (instance of WSDSL::Params)
  |             |    |  |_ Optional param rules
  |             |    |_ Required param rules
  |             |_ Namespaced params (array containing nested optional and required rules)
  |__ response (instance of WSDSL::Response)
  |      |_ elements (array of elements with each element having a name, type, attributes and vectors
  |            |  |_ attributes (array of WSDSL::Response::Attribute, each attribute has a name, a type, a doc and some extra options)
  |            |_ vectors (array of WSDSL::Response::Vector), each vector has a name, obj_type, & an array of attributes
  |                 |_ attributes (array of WSDSL::Response::Attribute, each attribute has a name, a type and a doc)
  |__ doc (instance of WSDSL::Documentation)
     |  |  | |_ overal) description
     |  |  |_ examples (array of examples as strings)
     |  |_ params documentation (Hash with the key being the param name and the value being the param documentation)
     |_ response (instance of Documentation.new)
          |_ elements (array of instances of WSDSL::Documentation::ElementDoc, each element has a name and a list of attributes)
                |_ attributes (Hash with the key being the attribute name and the value being the attribute's documentation)

Since:

  • 0.0.3

Defined Under Namespace

Classes: Doc, Documentation, Params, Response, ResponseExceptions

Constant Summary collapse

SERVICE_ROOT_REGEXP =

Since:

  • 0.0.3

/(.*?)[\/\(\.]/
SERVICE_ACTION_REGEXP =

/[/(.]([a-z0-9_]+)/i

Since:

  • 0.0.3

/[\/\(\.]([a-z0-9_]+)[\/\.\(\?]?/i
SERVICE_RESTFUL_SHOW_REGEXP =

//:[a-z0-9_]+.w3$/

Since:

  • 0.0.3

/\/:[a-z0-9_]+$/

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url) ⇒ WSDSL

Service constructor which is usually used via Kernel#describe_service

Parameters:

  • url (String) —

    Service’s url

See Also:

  • See how this class is usually initialized using `describe_service`

Since:

  • 0.0.3



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/wsdsl.rb', line 127

def initialize(url)
  @url                 = url
  @defined_params      = WSDSL::Params.new
  @doc                 = WSDSL::Documentation.new
  @response            = WSDSL::Response.new
  @exceptions          = WSDSL::ResponseExceptions.new
  @name                = extract_service_root_name(url)
  if WSDSL.use_pluralized_controllers
    base_name = ExtlibCopy::Inflection.pluralize(ExtlibCopy::Inflection.singular(name))
    @controller_name     = "#{ExtlibCopy.classify(base_name)}Controller"
  else
    @controller_name     = "#{ExtlibCopy.classify(name)}Controller"
  end
  @action              = extract_service_action(url)
  @verb                = :get
  @formats             = []
  @version             = '0.1'
  @ssl                 = false
  @auth_required       = true
  @extra               = {}
  @content_type        = nil
end

Instance Attribute Details

#action(a = nil) ⇒ Symbol

Sets and/or returns the service known exceptions

Parameters:

  • a (String, Symbol) (defaults to: nil) —

    Action to use for the service, such as :show

Returns:

  • (Symbol) —

    The service action

Since:

  • 0.0.3



329
330
331
332
 
# File 'lib/wsdsl.rb', line 329

def action(a=nil)
  @action = a.to_sym if a
  @action
end

#auth_required ⇒ Boolean (readonly)

Is authentication required?

Returns:

  • (Boolean)

Since:

  • 0.0.3



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

def auth_required
  @auth_required
end

#controller ⇒ WSController (readonly)

Controller instance associated with the service

Returns:

  • (WSController)

Since:

  • 0.0.3



78
79
80
 
# File 'lib/wsdsl.rb', line 78

def controller
  @controller
end

#controller_name(cn = nil) ⇒ String

Sets and/or returns the controller name

Parameters:

  • cn (String, Symbol) (defaults to: nil) —

    Controller name to use for the service

Returns:

  • (String) —

    The controller name

Since:

  • 0.0.3



339
340
341
342
 
# File 'lib/wsdsl.rb', line 339

def controller_name(cn=nil)
  @controller_name = cn.to_s if cn
  @controller_name
end

#defined_params ⇒ Array<WSDSL::Params> (readonly)

List of all the service params

Returns:

Since:

  • 0.0.3



54
55
56
 
# File 'lib/wsdsl.rb', line 54

def defined_params
  @defined_params
end

#doc ⇒ WSDSL::Documentation (readonly)

Documentation instance containing all the service doc

Returns:

Since:

  • 0.0.3



60
61
62
 
# File 'lib/wsdsl.rb', line 60

def doc
  @doc
end

#exceptions ⇒ Array<Class> (readonly)

Sets or returns the known exceptions

Parameters:

  • exception_classes (Class) —

    Known response exceptions

Returns:

  • (Array<Class>) —

    List of known exception classes

Since:

  • 0.0.3



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

def exceptions
  @exceptions
end

#extra ⇒ Hash (readonly)

Extra placeholder to store data in based on developer’s discretion.

Returns:

  • (Hash) —

    A hash storing extra data based.

Since:

  • 0.1



114
115
116
 
# File 'lib/wsdsl.rb', line 114

def extra
  @extra
end

#name ⇒ String (readonly)

Name of the service

Returns:

  • (String)

Since:

  • 0.0.3



95
96
97
 
# File 'lib/wsdsl.rb', line 95

def name
  @name
end

#ssl ⇒ Boolean (readonly)

Is SSL required?

Returns:

  • (Boolean)

Since:

  • 0.0.3



101
102
103
 
# File 'lib/wsdsl.rb', line 101

def ssl
  @ssl
end

#url ⇒ String (readonly)

Returns the service url

Returns:

  • (String) —

    The service url

Since:

  • 0.0.3



48
49
50
 
# File 'lib/wsdsl.rb', line 48

def url
  @url
end

#verb ⇒ Symbol (readonly)

The HTTP verb supported

Returns:

  • (Symbol)

Since:

  • 0.0.3



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

def verb
  @verb
end

#version ⇒ String (readonly)

Service’s version

Returns:

  • (String)

Since:

  • 0.0.3



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

def version
  @version
end

Class Method Details

.define_partial(name, &block) ⇒ Object

Since:

  • 0.0.3



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

def self.define_partial(name, &block)
  partials[name] = block
end

.partial(name, args) ⇒ Object

Since:

  • 0.0.3



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

def self.partial(name, args)
  partials[name].call(args) if(partials.has_key?(name))
end

.partials ⇒ Object

Since:

  • 0.0.3



150
151
152
 
# File 'lib/wsdsl.rb', line 150

def self.partials
  @partials     ||= {}
end

.use_pluralized_controllers ⇒ Boolean

Checks the WSDSL flag to see if the controller names are pluralized.

Returns:

  • (Boolean) —

    The updated value, default to false

Since:

  • 0.1.1



167
168
169
 
# File 'lib/wsdsl.rb', line 167

def self.use_pluralized_controllers
  @pluralized_controllers ||= false
end

.use_pluralized_controllers=(val) ⇒ Boolean

Sets a WSDSL global flag so all controller names will be automatically pluralized.

Parameters:

  • True (Boolean) —

    if the controllers are pluralized, False otherwise.

Returns:

  • (Boolean) —

    The updated value

Since:

  • 0.1.1



178
179
180
 
# File 'lib/wsdsl.rb', line 178

def self.use_pluralized_controllers=(val)
  @pluralized_controllers = val
end

Instance Method Details

#accept_no_params! ⇒ Nil

Mark the current service as not accepting any params. This is purely for expressing the developer’s objective since by default an error is raise if no params are defined and some params are sent.

Returns:

  • (Nil)

Since:

  • 0.0.3



283
284
285
286
 
# File 'lib/wsdsl.rb', line 283

def accept_no_params!
  # no op operation since this is the default behavior
  # unless params get defined. Makes sense for documentation tho.
end

#content_type(ct = nil) ⇒ String

Sets and/or returns the service content_type

Parameters:

  • Valid (String) —

    HTTP content_type like ‘multipart/form-data’

Returns:

  • (String) —

    The content type for this service

Since:

  • 0.0.3



271
272
273
274
 
# File 'lib/wsdsl.rb', line 271

def content_type(ct=nil)
 @content_type = ct if ct
 @content_type
end

#controller_dispatch(app) ⇒ #to_s

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Offers a way to dispatch the service at runtime Basically, it dispatches the request to the defined controller/action The full request cycle looks like that: client -> webserver -> rack -> env -> [service dispatcher] -> controller action -> rack -> webserver -> client

Parameters:

  • app (Object) —

    Reference object such as a Sinatra::Application to be passed to the controller.

Returns:

  • (#to_s) —

    The response from the controller action

Since:

  • 0.0.3



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/wsdsl.rb', line 190

def controller_dispatch(app)
  unless @controller
    begin
      @controller = Object
      @controller_name.split("::").each do |const|
        @controller = @controller.const_get(const)
      end
    rescue NameError => e
      @controller = nil
      raise "The #{@controller_name} class was not found"
    end
  end
  # We are passing the service object to the controller so the
  # param verification could be done when the controller gets initialized.
  @controller.new(app, self).send(@action)
end

#disable_auth ⇒ Boolean

Mark that the service doesn’t require authentication. Note: Authentication is turned on by default

Returns:

  • (Boolean)

Since:

  • 0.0.3



254
255
256
 
# File 'lib/wsdsl.rb', line 254

def disable_auth
  @auth_required = false
end

#documentation {|WSDSL::Documentation| ... } ⇒ WSDSL::Documentation

Yields and returns the documentation object

Yields:

Returns:

Since:

  • 0.0.3



362
363
364
 
# File 'lib/wsdsl.rb', line 362

def documentation
  yield(doc)
end

#enable_ssl ⇒ Boolean

Mark that the service requires a SSL connection

Returns:

  • (Boolean)

Since:

  • 0.0.3



262
263
264
 
# File 'lib/wsdsl.rb', line 262

def enable_ssl
  @ssl = true
end

#formats(*f_types) ⇒ Array<Symbol>

Sets or returns the supported formats

Parameters:

  • f_types (String, Symbol) —

    Format type supported, such as :xml

Returns:

  • (Array<Symbol>) —

    List of supported formats

Since:

  • 0.0.3



306
307
308
309
 
# File 'lib/wsdsl.rb', line 306

def formats(*f_types)
  f_types.each{|f| @formats << f unless @formats.include?(f) }
  @formats
end

#http_verb(s_verb = nil) ⇒ String, Symbol

Sets the accepted HTTP verbs or return it if nothing is passed.

Returns:

  • (String, Symbol)

Since:

  • 0.0.3



348
349
350
351
352
353
354
355
 
# File 'lib/wsdsl.rb', line 348

def http_verb(s_verb=nil)
  return @verb if s_verb.nil?
  @verb = s_verb.to_sym
  # Depending on the service settings and url, the service action might need to be updated.
  # This is how we can support restful routes where a PUT request automatically uses the update method.
  update_restful_action(@verb)
  @verb
end

#nested_params ⇒ Array<WSDSL::Params>

Returns an array of namespaced params

Returns:

See Also:

Since:

  • 0.0.3



245
246
247
 
# File 'lib/wsdsl.rb', line 245

def nested_params
  @defined_params.namespaced_params
end

#optional_rules ⇒ Array<WSDSL::Params::Rule>

Returns an array of optional param rules

Returns:

Since:

  • 0.0.3



236
237
238
 
# File 'lib/wsdsl.rb', line 236

def optional_rules
  @defined_params.list_optional
end

#params ⇒ WSDSL::Params Also known as: param

Returns the defined params for DSL use only! To keep the distinction between the request params and the service params using the defined_params accessor is recommended.

Returns:

See Also:

Since:

  • 0.0.3



215
216
217
218
219
220
221
 
# File 'lib/wsdsl.rb', line 215

def params
  if block_given?
    yield(@defined_params)
  else
    @defined_params
  end
end

#required_rules ⇒ Array<WSDSL::Params::Rule>

Returns an array of required param rules

Returns:

Since:

  • 0.0.3



228
229
230
 
# File 'lib/wsdsl.rb', line 228

def required_rules
  @defined_params.list_required
end

#response { ... } ⇒ WSDSL::Response

Returns the service response

Yields:

  • The service response object

Returns:

Since:

  • 0.0.3



293
294
295
296
297
298
299
 
# File 'lib/wsdsl.rb', line 293

def response
  if block_given?
    yield(@response)
  else
    @response
  end
end