citysdk 0.1.2.5 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f0fd4a218a56d9c50a060909e9d27308f7262b72
-  data.tar.gz: dbcead5631b8cd87d3844d319e51843ec3b859c6
+  metadata.gz: 969313e0796217d8f9e3ec407c477a01b8a83e26
+  data.tar.gz: 4d06bd0a1e14fefdd92699b80733d35b7747f2aa
 SHA512:
-  metadata.gz: 3c9c553e8e707ca27f07c12d57700c219471b60a5c1efeab62148f2912ab196cfd98739294143432cc6f63097d22beadeb5d10b0e5266e0ff91a56c8562327d1
-  data.tar.gz: 1ffd5cd48feaabef893c68b558e6e6ace96a3a2de6cbed74d9ef8ab4a6c76c3424c466b207ab7760dffb7e0006c374d5da436939a8b516ba815ba2a1c1472dec
+  metadata.gz: da86200998e771230aecbcb3027af48ce77d23190898dfb9a1b9a57865e15221833c5b16d4cb038a2e10af2f9ca9e4235b9ceba61bcf7f44385ad6f6a5652a6d
+  data.tar.gz: fe3e3978db2a0f0eab25d9ee109873fcc56a81fa865a8cd1f203b46878aa05dbd7cf194a7184bf4c6cdc5e364176a9258c0682db339dac0244b50d573e78a344

data/.gitignore

@@ -1 +1,34 @@
 *.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile.lock

@@ -1,32 +1,38 @@
 PATH
   remote: .
   specs:
-    citysdk (0.1.1.4)
-      charlock_holmes (>= 0.6.9.4)
-      dbf
-      faraday (>= 0.8.5)
-      georuby (>= 2.0.0)
+    citysdk (1.0)
+      charlock_holmes (~> 0.6)
+      curses (~> 1.0)
+      dbf (~> 2.0)
+      faraday (~> 0.8)
+      georuby (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    charlock_holmes (0.6.9.4)
-    dbf (2.0.6)
+    charlock_holmes (0.7.3)
+    curses (1.0.1)
+    dbf (2.0.7)
       fastercsv (~> 1.5.4)
-    diff-lcs (1.2.4)
-    faraday (0.8.7)
-      multipart-post (~> 1.1)
+    diff-lcs (1.2.5)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
     fastercsv (1.5.5)
-    georuby (2.0.0)
-    multipart-post (1.2.0)
-    rspec (2.14.0)
-      rspec-core (~> 2.14.0)
-      rspec-expectations (~> 2.14.0)
-      rspec-mocks (~> 2.14.0)
-    rspec-core (2.14.0)
-    rspec-expectations (2.14.0)
-      diff-lcs (>= 1.1.3, < 2.0)
-    rspec-mocks (2.14.1)
+    georuby (2.2.1)
+    multipart-post (2.0.0)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.2)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.2)
 
 PLATFORMS
   ruby
@@ -36,4 +42,4 @@ DEPENDENCIES
   citysdk!
   faraday
   georuby
-  rspec
+  rspec (~> 3.0)

data/README.md

@@ -1,47 +1,69 @@
-# Citysdk
+# CitySDK GEM
 
-The CitySDK gem encapulates the CItySDK API, and offers high-level file import functionalities.
-The CitySDK API is part of an (open)data distribution platform developed in the EU CitySDK program by [Waag Society](http://waag.org).
-Find the platform itself on [github](https://github.com/waagsociety/citysdk), platform documentation is [here](http://dev.citysdk.waag.org).
+The CitySDK gem encapulates the CitySDK LD-API, and offers high-level file import functionalities.
+The CitySDK LD-API is part of an (open)data distribution platform developed in the EU CitySDK program by [Waag Society](http://waag.org).
+Find the platform itself on [github](https://github.com/waagsociety/citysdk-ld), background is [here](http://dev.citysdk.waag.org).
+
+In order to best get an overview of the way to use the GEM to import files into the CitySDK LD-API, have a look at the 'admr' importer for the top-level administrative regions in the Netherlands.
+The data consists of three ESRI shape files; the importer is well commented, explaining most of the possibilities of the GEM. 
+Please download the importer [here](https://github.com/waagsociety/citysdk-amsterdam/tree/master/importers/admr)
+
+## Installation
+
+To install it just install the gem:
+
+    gem install citysdk
+
+If you're using Bundler, add the gem to Gemfile.
+
+    gem 'citysdk'
+
+Then run `bundle install`.
 
 
 ## Usage
+The GEM can be used on two different levels, either simply as a wrapper around the API, or as a means to read, convert and import various types of data files.
+The gem exposes it's functionality through three different objects:
+
+- CitySDK::API
+- CitySDK::FileReader
+- CitySDK::Importer
+
+The FileReader can be used stand-alone to read, edit and save data files, the Importer builds on the FileReader and API objects.
+
+The FileReader has support for CSV, Shape and (Geo)Json files. XML is currently not supported; we recommend [OpenRefine](https://github.com/OpenRefine/OpenRefine/wiki/Downloads) to convert these to either CSV or JSON.
+
+
+### CitySDK::API Usage
+
 
-    require 'citysdk'
-    
-    # check the dev site for api usage.
+CALL                                  | Description
+|:-------------------------------------|:-------------------------------------------------------
+`@api = CitySDK::API.new('<endpoint IP>')` | Establish a link to the particular endpoint
+`@api.authenticate('<name>','<password>')` | For reading this is not necessary, for writing and deleting you need to authenticate. The authentication times out if not used (is reset by writing to the API). This call takes an optional  block for immediate automatic release when the block has been called.
+`@api.get path` | Simply issue a 'GET' against the API; the results are returned as a ruby Hash.
+`@api.put path,data` | PUT a resource; see [Documentation](https://github.com/waagsociety/citysdk-ld/wiki/Objects)
+`@api.post path,data` | POST a resource; see [Documentation](https://github.com/waagsociety/citysdk-ld/wiki/Objects)
+`@api.patch path,data` | PATCH a resource; see [Documentation](https://github.com/waagsociety/citysdk-ld/wiki/Objects)
+`@api.delete path` | Issue a DELETE to the API; path points to the resource to delete. Requires authentication.
+`@api.release` | This call will flush any buffered object that were scheduled to be created or updated. See also batch_size, below.
+`@api.set_layer(layername)` | Set the the layer for subsequent 'create_object' calls. User must be authenticate for this layer in order to sucesfully create objects.
+`@api.create_object(objhash)` | Adds an object to the database. See also batch_size, below.
+`@api.layers` | Shortcut for `get '/layers'`
+`@api.owners` | Shortcut for `get '/owners'`
+`@api.objects(layer=nil)` | Shortcut for `get '/objects'`. When a layer name is supplied, returns only objects from with data on this layer, and the layerdata itself.
+`@api.next` | When more results are available, returns the next page.
+`@api.format = <format>` | Specify the output format. Currently supported are (Geo)JSON and (Geo)JSON-LD.
+`@api.page_size = <page_size>` | Specify the number of features returned; default is 25.
+`@api.batch_size = <n>` | When adding objects thorugh 'create_object', they are buffered until '<n>' objects are available, then a single call is issuesd to the API.
+`@api.last_result` | Returns a Hash with the last HTTP status and the headers returned from the last call.
 
-    api = CitySDK::API.new('api.citysdk.waag.org')
 
-    # simple GET
-    # GET requests do not need authentication
-    first10layers = api.get('/layers')
-    puts "Number of layers: #{first10layers[:record_count]}"
-    puts "First layer: #{JSON.pretty_generate(first10layers[:results][0])}"
-    
 
-    # authenticate for write actions.
-    exit if not api.authenticate(<email>,<passw>)
 
-    # make a layer
-    # when you own the 'my' top level layer domain: 
-    @api.put('/layers',{:data => {
-      :name => 'my.layer',
-      :description => 'for testing',
-      :organization => 'me',
-      :category => 'civic.test'
-    }})
 
-    # add data to this layer
-    # attach to the node representing the city of Rotterdam
-    api.put('/admr.nl.rotterdam/my.layer', {:data => {:key1=>'value1', :key2=>10}})
 
 
-    ...
-    
-    # don't forget to release! this will also send 'unfilled' batches to the backend.
-    api.release
-    
 
 ## Contributing
 
@@ -49,4 +71,4 @@ Find the platform itself on [github](https://github.com/waagsociety/citysdk), pl
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+5. Create new Pull Request