README.md in datapimp-1.0.0 vs README.md in datapimp-1.0.1
- old
+ new
@@ -1,211 +1,39 @@
-### Data driven API programming
+### Tools for working with common data sources
-This gem promotes a declarative style of developing JSON APIs that automates a lot of common patterns
-found in the development of systems which have multiple users, with multiple roles and permissions.
+A collection of CLI utilities for pulling both files and structured data
+from file sharing and collaboration services like Google Drive and
+Dropbox.
-An API is a collection of resources, and resources can be queried, or commands can be run against resources, each by certain users in certain ways depending on the user's authorization level.
+You can use this to pull down google spreadsheets and convert them to
+JSON structures, or to convert an excel spreadsheet on Dropbox to the
+same.
-The DSL provided by this gem allows you to accomplish the tasks of writing your API documentation, your integration tests, as well as your actual implementation code at the same time, and in such a way that exposes metadata.
+You can use this to sync the contents of a local folder on your system
+with the remote contents of a file share on Dropbox or Google Drive.
-Because the API exposes metadata about the resources it contains, their schemas, and the various policies and details about them, it is possible for API client libraries to configure themselves accordingly.
+And much more.
-### Example
+### Getting Started
-```ruby
- require 'datapimp/dsl'
-
- api :my_app => "My Application" do
- version :v1
-
- desc "Public users include anyone with access to the URL"
- policy :public_users do
- allow :books, :commands => false, :queries => true
- end
-
- desc "Authenticated users register and are given an auth token"
- policy :logged_in_users do
- authenticate_with :header => 'X-AUTH-TOKEN', :param => :auth_token
- allow :books, :commands => true, :queries => true
- end
-
- desc "Admin users have the admin flag set to true"
- policy :admin_users do
- extends :logged_in_users
- test :admin?
- end
- end
+```bash
+gem install datapimp
+datapimp help
```
-An API can be inspected:
+#### Available Commands
-```ruby
-api("My Application").authentication_header #=> "X-AUTH-TOKEN"
-api("My Application").policies #=> [:public_users, :logged_in_users, :admin_users]
-api("My Application").policy(:admin_users).resource(:books).allowed_commands #=> [:create, :update, :delete]
```
+ COMMANDS:
-An API is made up of resources:
+ config Shows the configuration options being used
+ config set manipulate configuration settings
+ help Display global or [command] help documentation
+ list spreadsheets list the spreadsheets which can be used as datasources
+ setup amazon setup integration with amazon
+ setup dropbox setup integration with dropbox
+ setup github setup integration with github
+ setup google setup integration with google drive
+ sync data Synchronize the contents of a local data store with its remote source
+ sync folder Synchronize the contents of a local folder with a file sharing service
-```ruby
- resource "Books" do
- serializer do
- desc "A unique id for the book", :type => :integer
- attribute :id
-
- desc "The title of the book", :type => :string
- attribute :title
-
- desc "The year the book was published", :type => :integer
- attribute :year
-
- desc "A reference to the author", :type => "Author"
- has_one :author
- end
-
- command :update, "Update a book's attributes" do
- # Will ensure the command is run with
- # Book.accessible_to(current_user).find(id).
- scope :accessible_to
-
- params do
- duck :id, :method => :to_s
-
- optional do
- string :title
- end
- end
- end
-
- query do
- start_from :scope => :accessible_to
-
- params do
- desc "The year the book was published (example: YYYY)"
- integer :year_published
- end
-
- role :admin do
- start_from :scope => :all
- end
- end
- end
```
-
-A resource can also be inspected:
-
-```ruby
-meta_data = api("My Application").resource("Books").meta_data
-
-meta_data.attributes # {:id => "The id of the book", :year_published => "The year it was published"}
-meta_data.commands => [:update]
-meta_data.command(:update).arguments #=> [:id, :year, :title]
-meta_data.command(:update).optional_arguments #=> [:year, :title]
-```
-
-This inspection goes a long way to some advanced features, such as
-automated documentation and integration test generation, or in writing
-tools for generating client libraries and the like.
-
-### Customizing the elements
-
-How are each of these behaviors is stored in code? In a way that will be
-very familiar to Rails developers, following common naming conventions
-and file organization patterns.
-
-```
-- app
- - commands
- - application_command.rb
- - create_book.rb
- - update_book.rb
- - contexts
- - application_context.rb
- - book_context.rb
- - serializers
- - book_serializer.rb
-```
-
-### Request Context: Current User, Resource, and REST
-
-From the programmer's perspective, a typical resource is made up of several request patterns:
-
-- Filter Context (index, show)
-- Commands (aka mutations. create, update, destroy)
-- Serializers (aka presenters, views)
-
-Each of these objects can be configured to behave in certain ways that may be dependent on the user or role making the request to interact with them.
-
-Most API requests can be thought of in the following ways:
-
-```ruby
-# A Typical read request ( query / filter or detail view )
-
-response = present( this_resource ) # resource -> filter context
- .to(this_user) # filter context: relevant for this user
- .in(this_presentation) # serializer: different slices / renderings
-
-response.cache_key # russian doll style / max-updated-at friendly
-response.etag # http client conditional get
-```
-
-The filter context and serializer classes make this easy. They also
-make writing -- or rather, generating -- documentation and tests very
-easy as well.
-
-```ruby
-# Typical mutation request ( create, update, delete )
-
-outcome = run(this_command)
- .as(this_user)
- .against(this_set_of_one_or_more_records)
- .with(these_arguments)
-
-outcome.success?
-
-outcome.error_messages
-
-outcome.result
-```
-
-The command class determines the specifics of the above style of
-request.
-
-### The Filter Context
-
-The filter context system is used to standardize the way we write
-typical index and show actions in a typical Rails app. A user is
-requesting to view a set of records, or an individual records.
-
-Given a user making a request to view a specific resource, we arrive at
-the 'filter context'. The filter context is responsible for 'scoping' a
-resource to the set of records that user is permitted to view.
-
-Based on the combination of parameters used to build that filter, we
-compute a cache key that simplifies the process of server caching and
-http client caching at the same time.
-
-The filter context itself and the available parameters and their allowed
-values are specified by the DSL, which simplifies the process of writing
-complex queries and also provides configuration meta-data that aids in
-the process of developing client user interfaces, API documentation, and
-test code.
-
-### Commands
-
-The command class allows you to declare the available parameters, the
-required values, their data types, etc. It also allows you to declare
-which users can run the command, and further restrict the parameters
-allowed and the values they accept.
-
-### Serializers
-
-- ActiveModel Serializers
-- Documentation DSL
-- Metadata for inspection + documentation generation
-
-## API Documentation & Integration Tests
-
-- rspec_api_documentation gem
-- plan: take advantage of metadata defined above to auto-generate
- documentation with the ability to pass expectation blocks as pass /
- fail indicators