Permalink
Browse files

initial commit, added README and SPEC

  • Loading branch information...
0 parents commit 3b345f86b330948ea5652b1c1c62f8a26869b990 @steveklabnik committed Nov 6, 2011
Showing with 301 additions and 0 deletions.
  1. +4 −0 .gitignore
  2. +4 −0 Gemfile
  3. +118 −0 README.md
  4. +1 −0 Rakefile
  5. +146 −0 SPEC.md
  6. +20 −0 hateoas.gemspec
  7. +5 −0 lib/hateoas.rb
  8. +3 −0 lib/hateoas/version.rb
@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in hateoas.gemspec
+gemspec
118 README.md
@@ -0,0 +1,118 @@
+
+About
+=====
+
+HATEOAS helps you build hypermedia API clients, by providing a simple
+interface to navigate through pages, submitting forms, and caching local
+responses.
+
+The current version is 0.0.1.
+
+Find out more at [the hateoas homepage][homepage].
+
+Installing
+==========
+
+Become a HATEr by using Rubygems:
+
+```
+gem install hateoas
+```
+
+Usage
+=====
+
+Primarily, you'll use HATEOAS to help create your own gem to interact with your
+API. We'll pretend that you're writing an API to your own blogging
+software, since blogs are the Rails "Hello world" project.
+
+Right now, HATEOAS assumes that you use XHTML5 to drive your API.
+
+Configuration
+-------------
+
+The first thing you need to do is configure HATEOAS. Congratulations on
+creating a hypermedia API; it means the configuration is minimal! Simply
+assign your root URI like this:
+
+```
+Hateoas.base_uri = "http://api.hackety-hack.com"
+```
+
+HATEOAS has environment variables that make it easy to hit your local copy in
+development mode. By default, HATEOAS assumes you're using pow, and so it will
+append '.dev' onto the end of your `base_uri` when it is in development
+mode. To use something else, set the `development_base_uri`:
+
+```
+HATEOAS.develoment_base_uri = "http://localhost:9292"
+```
+
+The `HATEOAS_ENV` variable will control which configuration is used. Just like
+Rails, there are development, test, and production modes.
+
+In my own APIs, I prefer to use URIs for my rel attributes. If you also do
+this, there's an optional variable that makes using URIs simpler. Without it,
+here's how you navigate to the 'new post' page, then the 'new comments'
+page:
+
+```
+Hateoas::DSL.click_link("/rels/new-post")
+Hateoas::DSL.click_link("/rels/new-comments")
+```
+
+And with it:
+
+```
+Hateoas.rel_namespace = "rels"
+
+Hateoas::DSL.click_link("new-post")
+Hateoas::DSL.click_link("new-comments")
+```
+
+Groovy?
+
+DSL
+---
+
+HATEOAS provides a `DSL` module with all of the DSL methods you'll need. You
+can use these methods in two ways: One is to reference them by using their fully
+qualified names:
+
+```
+Hateoas::DSL.click_link("new-post")
+```
+
+Optionally, if you're building your own infrastructure around all of this, you
+can include the module inside your own class:
+
+```
+class MyApi
+ include Hateoas::DSL
+
+ def navigate(path)
+ click_link(path)
+ end
+end
+```
+
+The rest of this documentation will simply use `visit` rather than
+`Hateoas::DSL.visit`.
+
+Navigation
+----------
+
+If you read the previous section, you've got this one figured out: simply give
+a rel to the `click_link` method:
+
+```
+click_link("new-post")
+```
+
+Getting Data Back
+-----------------
+
+You can access the data on the current page by using the `current_page`
+method.
+
+[homepage][http://steveklabnik.github.com/cereal]
@@ -0,0 +1 @@
+require "bundler/gem_tasks"
146 SPEC.md
@@ -0,0 +1,146 @@
+
+About
+=====
+
+HATEOAS helps you build hypermedia API clients, by providing a simple
+interface to navigate through pages, submitting forms, and caching local
+responses.
+
+The current version is 0.0.1.
+
+Find out more at [the hateoas homepage][homepage].
+
+Installing
+==========
+
+Become a HATEr by using Rubygems:
+
+```
+gem install hateoas
+```
+
+Usage
+=====
+
+Primarily, you'll use HATEOAS to help create your own gem to interact with your
+API. We'll pretend that you're writing an API to your own blogging
+software, since blogs are the Rails "Hello world" project.
+
+Right now, HATEOAS assumes that you use XHTML5 to drive your API.
+
+Configuration
+-------------
+
+The first thing you need to do is configure HATEOAS. Congratulations on
+creating a hypermedia API; it means the configuration is minimal! Simply
+assign your root URI like this:
+
+```
+Hateoas.base_uri = "http://api.hackety-hack.com"
+```
+
+HATEOAS has environment variables that make it easy to hit your local copy in
+development mode. By default, HATEOAS assumes you're using pow, and so it will
+append '.dev' onto the end of your `base_uri` when it is in development
+mode. To use something else, set the `development_base_uri`:
+
+```
+HATEOAS.develoment_base_uri = "http://localhost:9292"
+```
+
+The `HATEOAS_ENV` variable will control which configuration is used. Just like
+Rails, there are development, test, and production modes.
+
+In my own APIs, I prefer to use URIs for my rel attributes. If you also do
+this, there's an optional variable that makes using URIs simpler. Without it,
+here's how you navigate to the 'new post' page, then the 'new comments'
+page:
+
+```
+Hateoas::DSL.click_link("/rels/new-post")
+Hateoas::DSL.click_link("/rels/new-comments")
+```
+
+And with it:
+
+```
+Hateoas.rel_namespace = "rels"
+
+Hateoas::DSL.click_link("new-post")
+Hateoas::DSL.click_link("new-comments")
+```
+
+Groovy?
+
+DSL
+---
+
+HATEOAS provides a `DSL` module with all of the DSL methods you'll need. You
+can use these methods in two ways: One is to reference them by using their fully
+qualified names:
+
+```
+Hateoas::DSL.click_link("new-post")
+```
+
+Optionally, if you're building your own infrastructure around all of this, you
+can include the module inside your own class:
+
+```
+class MyApi
+ include Hateoas::DSL
+
+ def navigate(path)
+ click_link(path)
+ end
+end
+```
+
+The rest of this documentation will simply use `visit` rather than
+`Hateoas::DSL.visit`.
+
+Navigation
+----------
+
+If you read the previous section, you've got this one figured out: simply give
+a rel to the `click_link` method:
+
+```
+click_link("new-post")
+```
+
+Getting Data Back
+-----------------
+
+You can access the data on the current page by using the `current_page`
+method.
+
+Forms
+-----
+
+There are a few methods to interact with forms:
+
+```
+fill_in('First Name', :with => 'John')
+fill_in('Password', :with => 'Seekrit')
+fill_in('Description', :with => 'Really Long Text...')
+choose('A Radio Button')
+check('A Checkbox')
+uncheck('A Checkbox')
+attach_file('Image', '/path/to/image.jpg')
+select('Option', :from => 'Select Box')
+```
+
+Caching
+-------
+
+HATEOAS includes a client-side cache, and respects HTTP caching directives.
+This helps with performance, and keeps network connections down.
+
+Authorization
+-------------
+
+Authentication
+--------------
+
+[homepage][http://steveklabnik.github.com/cereal]
@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "hateoas/version"
+
+Gem::Specification.new do |s|
+ s.name = "hateoas"
+ s.version = Hateoas::VERSION
+ s.authors = ["Steve Klabnik"]
+ s.email = ["steve@steveklabnik.com"]
+ s.homepage = "http://steveklabnik.github.com/hateoas"
+ s.summary = %q{Build easy clients for Hypermedia APIs.}
+ s.description = %q{A set of tools to help build clients for Hypermedia APIs.}
+
+ s.files = `git ls-files`.split("\n")
+ s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+ s.executables = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+ s.require_paths = ["lib"]
+
+ s.add_development_dependency "rspec"
+end
@@ -0,0 +1,5 @@
+require "hateoas/version"
+
+module Hateoas
+ # Your code goes here...
+end
@@ -0,0 +1,3 @@
+module Hateoas
+ VERSION = "0.0.1"
+end

0 comments on commit 3b345f8

Please sign in to comment.