• This repository has been archived on 02/Jan/2018
  • Stars
    star
    438
  • Rank 99,453 (Top 2 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 12 years ago
  • Updated about 11 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

DSL to describe, document and test web services

Web Service DSL

CI Build Status

Weasel Diesel is a DSL to describe and document your web API.

To get you going quickly, see the generator for sinatra apps. The wd_sinatra gem allows you to generate the structure for a sinatra app using Weasel Diesel and with lots of goodies. Updating is trivial since the core features are provided by this library and the wd_sinatra gem.

You can also check out this Sinatra-based example application that you can fork and use as a base for your application.

DSL examples:

describe_service "/hello_world" do |service|
  service.formats   :json
  service.http_verb :get # default verb, can be ommitted.
  service.disable_auth # on by default

  # INPUT
  service.param.string  :name, :default => 'World', :doc => "The name of the person to greet."

  # OUTPUT
  service.response do |response|
    response.object do |obj|
      obj.string :message, :doc => "The greeting message sent back. Defaults to 'World'"
      obj.datetime :at, :doc => "The timestamp of when the message was dispatched"
    end
  end

  # DOCUMENTATION
  service.documentation do |doc|
    doc.overall "This service provides a simple hello world implementation example."
    doc.example "<code>curl -I 'http://localhost:9292/hello_world?name=Matt'</code>"
 end

  # ACTION/IMPLEMENTATION (specific to the sinatra app example, can
  # instead be set to call a controller action)
  service.implementation do
    {:message => "Hello #{params[:name]}", :at => Time.now}.to_json
  end

end

Or a more complex example using XML:

    SpecOptions = ['RSpec', 'Bacon'] # usually pulled from a model

    describe_service "/wsdsl/test.xml" do |service|
      service.formats  :xml, :json
      service.http_verb :get

      # INPUT
      service.params do |p|
        p.string :framework, :in => SpecOptions, :null => false, :required => true

        p.datetime :timestamp,
                   :default => Time.now,
                   :doc => "The test framework used, could be one of the two following: #{SpecOptions.join(", ")}."

        p.string   :alpha,     :in      => ['a', 'b', 'c']
        p.string   :version,
                   :null    => false,
                   :doc => "The version of the framework to use."

        p.integer  :num,      :minvalue => 42
        p.namespace :user do |user|
          user.integer :id, :required => :true
        end
      end

      # OUTPUT
      # the response contains a list of player creation ratings each object in the list
      service.response do |response|
        response.element(:name => "player_creation_ratings") do |e|
          e.attribute  :id          => :integer, :doc => "id doc"
          e.attribute  :is_accepted => :boolean, :doc => "is accepted doc"
          e.attribute  :name        => :string,  :doc => "name doc"

          e.array :name => 'player_creation_rating', :type => 'PlayerCreationRating' do |a|
            a.attribute :comments  => :string,  :doc => "comments doc"
            a.attribute :player_id => :integer, :doc => "player_id doc"
            a.attribute :rating    => :integer, :doc => "rating doc"
            a.attribute :username  => :string,  :doc => "username doc"
          end
        end
      end

      # DOCUMENTATION
      service.documentation do |doc|
        # doc.overall <markdown description text>
        doc.overall <<-DOC
         This is a test service used to test the framework.
        DOC

        # doc.example <markdown text>
        doc.example <<-DOC
    The most common way to use this service looks like that:
        http://example.com/wsdsl/test.xml?framework=rspec&version=2.0.0
        DOC
      end
    end

INPUT DSL

As shown in the two examples above, input parameters can be:

  • optional or required
  • namespaced
  • typed
  • marked as not being null if passed
  • set to have a value defined in a list
  • set to have a min value
  • set to have a min length
  • set to have a max value
  • set to have a max length
  • documented

Most of these settings are used to verify the input requests.

Supported defined types:

  • integer
  • float, decimal
  • string
  • boolean
  • array (comma delimited string)
  • binary, file

Note regarding required vs optional params.

You can't set a required param to be :null => true, if you do so, the setting will be ignored since all required params have to be present.

If you set an optional param to be :null => false, the verification will only fail if the param was present in the request but the passed value is nil. You might want to use that setting if you have an optional param that, by definition isn't required but, if passed has to not be null.

Validation and other param options

You can set many rules to define an input parameter. Here is a quick overview of the available param options, check the specs for more examples. Options can be combined.

  • required by default the defined optional input parameters are optional. However their presence can be required by using this flag. (Setting :null => true will be ignored if the paramter is required) Example: service.param.string :id, :required => true
  • in or options limits the range of the possible values being passed. Example: service.param.string :skills, :options %w{ruby scala clojure}
  • default sets a value for your in case you don't pass one. Example: service.param.datetime :timestamp, :default => Time.now.iso8601
  • min_value forces the param value to be equal or greater than the option's value. Example: `service.param.integer :age, :min_value => 21
  • max_value forces the param value to be equal or less than the options's value. Example: `service.param.integer :votes, :max_value => 7
  • min_length forces the length of the param value to be equal or greater than the option's value. Example: service.param.string :name, :min_length => 2
  • max_length forces the length of the param value to be equal or lesser than the options's value. Example: service.param.string :name, :max_length => 251
  • null in the case of an optional parameter, if the parameter is being passed, the value can't be nil or empty.
  • doc document the param.

Namespaced/nested object

Input parameters can be defined nested/namespaced. This is particuliarly frequent when using Rails for instance.

service.params do |param|
    param.string :framework,
      :in => ['RSpec', 'Bacon'],
      :required => true,
      :doc => "The test framework used, could be one of the two following: #{WeaselDieselSpecOptions.join(", ")}."

    param.datetime :timestamp, :default => Time.now
    param.string   :alpha,     :in      => ['a', 'b', 'c']
    param.string   :version,   :null    => false, :doc => "The version of the framework to use."
    param.integer  :num,       :min_value => 42,  :max_value => 1000, :doc => "The number to test"
    param.string   :name,      :min_length => 5, :max_length => 25
  end

  service.params.namespace :user do |user|
    user.integer :id, :required => :true
    user.string  :sex, :in => %Q{female, male}
    user.boolean :mailing_list, :default => true, :doc => "is the user subscribed to the ML?"
    user.array   :skills, :in => %w{ruby js cooking}
  end

  service.params.namespace :attachment, :null => true do |attachment|
    attachment.string :url, :required => true
  end

Here is the same type of input but this time using a JSON jargon, namespace and object are aliases and can therefore can be used based on how the input type.

# INPUT using 1.9 hash syntax
service.params do |param|
  param.integer :playlist_id,
            doc: "The ID of the playlist to which the track belongs.",
            required: true
  param.object :track do |track|
    track.string :title,
                  doc: "The title of the track.",
                  required: true
    track.string :album_title,
                  doc: "The title of the album to which the track belongs.",
                  required: true
    track.string :artist_name,
                  doc: "The name of the track's artist.",
                  required: true
    track.string :rdio_id,
                  doc: "The Rdio ID of the track.",
                  required: true
  end
end

OUTPUT DSL

JSON API example

Consider the following JSON response:

    { people: [
      {
        id : 1,
        online : false,
        created_at : 123123123123,
        team : {
          id : 1231,
          score : 123.32
        }
      },
      {
        id : 2,
        online : true,
        created_at : 123123123123,
        team: {
          id : 1233,
          score : 1.32
        }
      },
    ] }

It would be described as follows:

    describe_service "/json_list" do |service|
      service.formats  :json
      service.response do |response|
        response.array :people do |node|
          node.integer :id
          node.boolean :online
          node.datetime :created_at
          node.object :team do |team|
            team.integer :id
            team.float :score, :null => true
          end
        end
      end
    end

Nodes/elements can also use some meta-attributes including:

  • key : refers to an attribute name that is key to this object
  • type : refers to the type of object described, valuable when using JSON across OO based apps.

JSON response validation can be done using an optional module as shown in (spec/json_response_verification_spec.rb)[https://github.com/mattetti/Weasel-Diesel/blob/master/spec/json_response_verification_spec.rb]. The goal of this module is to help automate API testing by validating the data structure of the returned object.

Another simple examples:

Actual output:

{"organization": {"name": "Example"}}

Output DSL:

describe_service "example" do |service|
  service.formats  :json
  service.response do |response|
    response.object :organization do |node|
      node.string :name
    end
  end
end

Actual output:

 {"name": "Example"}

Output DSL:

describe_service "example" do |service|
  service.formats  :json
  service.response do |response|
    response.object do |node|
      node.string :name
    end
  end
end

Documentation generation

    $ weasel_diesel generate_doc <SOURCE_PATH> <DESTINATION_PATH>

To generate documentation for the APIs you created in the api folder. The source path is the location of your ruby files. The destination is optional, 'doc' is the default.

Here's a sample of what the generator documentation looks like.

Test Suite & Dependencies

The test suite requires rspec, rack, and sinatra gems.

Copyright

Copyright (c) 2012 Matt Aimonetti. See LICENSE for further details.

More Repositories

1

googlecharts

Ruby Google Chart API
Ruby
699
star
2

merb-book

Open Source Merb book
Ruby
186
star
3

acts_as_taggable_on_steroids

(OBSOLETE) This plugin is based on acts_as_taggable by DHH but includes extras
Ruby
152
star
4

filebuffer

filebuffer is a package implementing a few file-like interfaces. The implementation is backed by a byte buffer. The main purpose is to have in-memory file alternative.
Go
142
star
5

sinatra-web-api-example

Example application using Sinatra and the DSL gem to develop web APIs using a simple DSL and a small stack.
JavaScript
121
star
6

MacRuby--The-Definitive-Guide

MacRuby: The Definitive Guide - code repo
Ruby
119
star
7

goRailsYourself

A suite of useful functions needed when porting/mixing Go/Rails code.
Go
93
star
8

mimetype-fu

get the mimetype of a file directly in Ruby
Ruby
83
star
9

wd-sinatra

Weasel-Diesel Sinatra app gem, allowing you to generate/update sinatra apps using the Weasel Diesel DSL
Ruby
75
star
10

audio

This is a playground, production ready code is available at https://github.com/go-audio/
Go
74
star
11

goHtmlTemplateExample

Example setting up a Golang web server with static files, HTML templates and Angular.js
Go
67
star
12

globalite

Globalite is meant to be a breed of the best i18n /l10n plugins available for Rails.
Ruby
60
star
13

m3u8Grabber

Experimental command line tool downloading the content of a m3u8 file containing TS video segments and converting them to mkv.
Go
58
star
14

macruby_graphics

Cocoa's Core Graphics & Core Image wrapper for MacRuby (see original author's branch in the link below)
Ruby
57
star
15

ok-go

Google Assistant SDK in Go
Go
57
star
16

GC-stats-middleware

Ruby GC Stats after each request (rack middleware)
50
star
17

fire-and-forget

[Not maintained] Very dumb HTTP "client" that fires requests and doesn't care about the response.
Ruby
44
star
18

ruby-web-search

A Ruby gem that provides a way to retrieve search results via the main search engines using Ruby
Ruby
44
star
19

i18n

Basic internationalization(i18n) library for Ruby
Ruby
36
star
20

LiveTV

Simple OS X application allowing you to watch some live free TV channels (French, English, Italian).
Objective-C
33
star
21

macruby-httpwrapper

simplified http wrapper for MacRuby/RubyMotion using delegation/ruby block
Ruby
29
star
22

phileas_frog

MacRuby video game using Cocoa's CoreAnimation
Ruby
27
star
23

waveform_demo

Flutter Waveform drawing demo repo
Dart
24
star
24

go-web-api-demo

Example implementation of a web API in Go
Go
22
star
25

sm-808

Programming exercise - code the sequencer part of a Drum Machine
21
star
26

merb_babel

Merb Babel is a dead simple translation/localization tool for Merb
Ruby
19
star
27

pluzzdl

My own fork of pluzzdl
Python
17
star
28

noko-vs-builder-benchmark

Rails app to benchmark Nokogiri's XML builder vs Builder
Ruby
15
star
29

WSDSL

Due to a confusing name, this project was renamed and moved to:
Ruby
14
star
30

macruby-json

reimplementation of the ruby json gem for macruby using objc
Ruby
13
star
31

ar-backup

Active Record backup is a Rails plugin which lets you backup your database schema and content in a schema.rb file and fixtures.
Ruby
13
star
32

MacRuby-Siri

Simple demo showing how to use the voice recognition feature of OS X to implement a Siri-like app in MacRuby,
Ruby
13
star
33

macruby-doc-app

simple experiment to query the cocoa and eventually the macruby doc
Ruby
13
star
34

globalite-example

Sample app showing how to implement GlobaLite in a Rails app
Ruby
11
star
35

merb-static-pages-slice

Use markdown files to store and serve static pages (about us, contact us, etc)
Ruby
11
star
36

multibyte

Ruby Multibyte library extracted from ActiveSupport
Ruby
10
star
37

Pvwatts

Wrapper around the http://www.nrel.gov/rredc/pvwatts/ web service API
Ruby
10
star
38

sinatra-wsdsl-example

moved to https://github.com/mattetti/sinatra-web-api-example
JavaScript
10
star
39

TVFrancaise

Simple OS X application allowing you to watch most of the free French TV channels live. (works overseas)
Ruby
10
star
40

apple-remote-wrapper

fork of Martin Kahr work on an Apple Remote Wrapper
Objective-C
8
star
41

IOLI-crackme

crackme exercises with instructions to learn in a safe environment
C++
7
star
42

monkey_patcher

keep track of your monkey patches
7
star
43

google-speech

Fun with Google Cloud Platform speech recognition API
Go
7
star
44

fasthttp

FastHTTP is a Ruby library suitable for use as a drop-in Net::HTTP replacement or with event frameworks like EventMachine and Rev
C
6
star
45

swx-ruby

Ruby implementation of SWX RPC
Ruby
6
star
46

cocoa

Pure Go reimplementation of some Cocoa specific features.
Go
6
star
47

simple_merb_example_app

simple app example, look at the branches to see how to build the app
Ruby
6
star
48

dm-gvideo-adapter

DataMapper adapter for google video
Ruby
6
star
49

herbs

Hopefully Exhaustive Ruby Benchmark Suite
Ruby
5
star
50

merb_training_site

5
star
51

Box2d

My Box2d fork which has the iPhone TestBed compiling under Xcode4
C++
5
star
52

hotocoa-roundtransparentwindow

HotCocoa(MacRuby) port of Apple's RoundTransparentWindow sample using a Nib
5
star
53

MacRuby-Chipmunk

Cocoa Framework designed to use Chipmunk Physics with MacRuby
C
5
star
54

MrStuff

MacRuby experimental wrappers
Ruby
5
star
55

merb-misc

misc stuff related to Merb
Ruby
5
star
56

RubyConfX-code

The code used for my MacRuby talk at RubyConf X | demos: iVoiceControl (voice recognition), PS3 controller + MacRuby + HTML5, tokenization, headless browser and gowalla sample.
JavaScript
5
star
57

sdruby-raffle

Tiny Ruby gem to pick raffle winners
Ruby
4
star
58

merb_latest_rss_items_slice

Just a test Merb Slice displaying the latest RSS items from a feed
Ruby
4
star
59

PS3SixAxis

Use a PS3 Dualshock 3 Controller with Cocoa
JavaScript
4
star
60

drumbeat

Drum beat is a Go library to handle drum beat patterns
Go
4
star
61

ma-agile

CSS
4
star
62

learning_scala

Misc stuff you might care about when learning scala
Scala
4
star
63

plex-web-client

JavaScript
4
star
64

uuid

Go UUID package - use at your own risk
Go
4
star
65

artist_portfolio

Shoes app displaying an artist portfolio using Flickr as a source for content
Ruby
4
star
66

phare

native osx client for lighthouseapp.com
Ruby
4
star
67

mattetti.github.com.old

Matt Aimonetti's home page
JavaScript
4
star
68

merb-book-tmbundle

A TextMate bundle for the merb-book bundle
3
star
69

couchrest-app

CouchApp for CouchRest logger middleware. Browse and analyze your logs directly from Couch
JavaScript
3
star
70

cbc

CBC/radio-canada has great content and in some cases, one might be interested in keeping a backup
Go
3
star
71

MacRuby-NSCollectionView

example for @tronathan
Ruby
3
star
72

bottetti

my irc bot
CoffeeScript
3
star
73

scrapbook

Experiment designed to reflect on the organization of web scraping/data processing.
Ruby
3
star
74

go-exercises

Hopefully fun exercises in Golang. Each exercise has a test suite and your mission to make it pass!
Go
3
star
75

merb-doc

Stuff to generate docs for Merb outside of an app
Ruby
3
star
76

pubnub-publisher

A Ruby publisher gem for PubNub (for those who only care about publishing from Ruby)
Ruby
2
star
77

macruby-raffle

raffle app
Ruby
2
star
78

macruby-roundtransparentwindow

MacRuby port of Apple's RoundTransparentWindow sample
Ruby
2
star
79

sandbox

testing different things, nothing very interesting
Ruby
2
star
80

pastis

fresh and relaxing experimentation
Ruby
2
star
81

misc-Python-experiments

nothing valuable in here, just me playing with Python
Python
2
star
82

dm-websearch-adapter

2
star
83

ruby_practice

series of random exercises to practice Ruby
Ruby
2
star
84

MacRuby-ScriptingBridge-Browser

A ScriptingBridge browser for MacRuby, quite like AppleScript Editor's dictionary browser.
Objective-C
2
star
85

sigen

signature generator written in Ruby and using RMagick
Ruby
2
star
86

merbthor

2
star
87

UnityAzureSpeechSynthesis

Quick demo showing how to use Azure Speech Synthesis (tts) from Unity and loading/playing the generated file in game.
ShaderLab
2
star
88

gvideo

retrieve a google user's list of videos using his user id.
Ruby
2
star
89

LCFF

Luca's Cow Fart Filter
Go
2
star
90

http-proxy-experiment

Simple http proxy server written in Go to learn the language. The goal of this server is to proxy some defined websites with full cookie support.
Go
1
star
91

ruby-exercises

simple katas and exercises prepared for SDRuby meetups.
Ruby
1
star
92

bugsnag-go

bugsnag.com API client in Go
Go
1
star
93

twitter_game_bot

A twitter bot
Ruby
1
star
94

revel_addons

Series of packages for the Revel Go Framework
Go
1
star
95

s2s-auth

s2s auth gem based on ActiveSupport's crypto
Ruby
1
star
96

paca

Selenium IDE test case converter to Go tests to be run via Agouti
Go
1
star
97

wd_sinatra_active_record

ActiveRecord helper for Weasel Diesel Sinatra apps. See https://github.com/mattetti/wd-sinatra
Ruby
1
star
98

Andromeda

The goal is to provide a highly concurrent public facing API that dispatches requests to other APIs via different protocols (HTTP, Thrift..)
Scala
1
star
99

webserver-test-plan

Shell
1
star
100

macruby-twitter_engine

MGTwitterEngine package for MacRuby/HotCocoa
Objective-C
1
star