README.rdoc in ruby_odata-0.0.9 vs README.rdoc in ruby_odata-0.0.10
- old
+ new
@@ -4,27 +4,37 @@
== Resources
* Source Code (hosted on GitHub): http://github.com/visoft/ruby_odata
* Documentation (hosted on rdoc.info): http://rdoc.info/projects/visoft/ruby_odata
-* Issue tracking (hosted on Lighthouse): http://visoft.lighthouseapp.com/projects/54309/home
+* Issue tracking (hosted on GitHub): https://github.com/visoft/ruby_odata/issues
* Wiki (hosted on GitHub): http://wiki.github.com/visoft/ruby_odata/
* Gem (hosted on Gemcutter): http://gemcutter.org/gems/ruby_odata
* Blog articles: {Introducing a Ruby OData Client Library}[http://bit.ly/IntroRubyOData]
+ {Ruby OData Update v0.0.7}[http://bit.ly/ruby_odata007]
+ {Ruby OData Update v0.0.8}[http://bit.ly/ruby_odata008]
+ {Ruby OData Update v0.0.10}[http://bit.ly/ruby_odata0010]
== Installation
You can install ruby_odata as a gem using:
gem install ruby_odata
== Usage
+=== Instantiating the Service
+There are various options that you can pass when creating an instance of the service, these include:
+* username: username for http basic auth
+* password: password for http basic auth
+* verify_ssl: false if no verification, otherwise mode (OpenSSL::SSL::VERIFY_PEER is default)
+* additional_params: a hash of query string params that will be passed on all calls (query, new, update, delete, batch)
+
=== Adding
When you point at a service, an AddTo<EntityName> method is created for you. This method takes in the new entity to create. To commit the change, you need to call the save_changes method on the service. To add a new category for example, you would simply do the following:
require 'ruby_odata'
- svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc"
+ svc = OData::Service.new "http://127.0.0.1:8989/SampleService/Entities.svc"
new_category = Category.new
new_category.Name = "Sample Category"
svc.AddToCategories(new_category)
category = svc.save_changes
puts category.to_json
@@ -32,11 +42,11 @@
=== Updating
To update an object, simply pass the modified object to the update_object method on the service. Updating, like adding requires you to call save_changes in order to persist the change. For example:
require 'ruby_odata'
- svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc"
+ svc = OData::Service.new "http://127.0.0.1:8989/SampleService/Entities.svc"
new_category = Category.new
new_category.Name = "Sample Category"
svc.AddToCategories(new_category)
category = svc.save_changes
puts category.to_json
@@ -49,11 +59,11 @@
=== Deleting
Deleting an object involves passing the tracked object to the delete_object method on the service. Deleting is another function that involves the save_changes method (to commit the change back to the server). In this example, we'll add a category and then delete it.
require 'ruby_odata'
- svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc"
+ svc = OData::Service.new "http://127.0.0.1:8989/SampleService/Entities.svc"
new_category = Category.new
new_category.Name = "Sample Category"
svc.AddToCategories(new_category)
category = svc.save_changes
puts category.to_json
@@ -65,11 +75,11 @@
=== Querying
Querying is easy, for example to pull all the categories from the SampleService, you simply can run:
require 'ruby_odata'
- svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc"
+ svc = OData::Service.new "http://127.0.0.1:8989/SampleService/Entities.svc"
svc.Categories
categories = svc.execute
puts categories.to_json
You can also expand, add filters, order, skip records, and take only the top X records to the query before executing it. For example:
@@ -157,11 +167,11 @@
=== Authentication
Basic HTTP Authentication is supported via sending a username and password as service constructor arguments:
require 'ruby_odata'
- svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc", { :username => "bob", :password=> "12345" }
+ svc = OData::Service.new "http://127.0.0.1:8989/SampleService/Entities.svc", { :username => "bob", :password=> "12345" }
=== SSL/https Certificate Verification
The certificate verification mode can be passed in the options hash via the :verify_ssl key. For example, to ignore verification in order to use a self-signed certificate:
require 'ruby_odata'
@@ -175,10 +185,10 @@
svc = OData::Service.new "https://127.0.0.1:44300/SampleService/Entities.svc", { :verify_ssl => OpenSSL::SSL::VERIFY_PEER }
Default verification is OpenSSL::SSL::VERIFY_PEER. Note due to the way Ruby's Request object implements certificate checking, you CAN NOT pass OpenSSL::SSL::VERIFY_NONE, you must instead pass a boolean false.
== Tests
-All of the tests are written using Cucumber going against a sample service (Found in /test/SampleService/*). The SampleService is an ASP.NET Web Site running a SQLEXPRESS 2008 R2 Database (TestDB), as well as the ADO.NET Entity Framework and a WCF Data Service. In order to run the tests, you need to spin up the SampleService and have it running on port 8888 (http://localhost:8888/SampleService).
+All of the tests are written using Cucumber going against a sample service (Found in /test/SampleService/*). The SampleService is an ASP.NET Web Site running a SQLEXPRESS 2008 R2 Database (TestDB), as well as the ADO.NET Entity Framework and a WCF Data Service. In order to run the tests, you need to spin up the SampleService and have it running on port 8989 (http://localhost:8989/SampleService).
One way to do this is to open the SampleService within Visual Studio 2010 and run it from there (must use IIS instead of development web server in order for basic auth tests to pass, however). Another option is to use IIS Express. It is a free download from Microsoft. Once installed, there is a batch file found in /test called "iisExpress x64.bat", you can run the batch file and just close the command window. There is a also an "iisExpress x86.bat" file for those of you running a 32-bit machine. The only difference is the path to the Program Files directory. Once you run the batch file, the web server will spin up and you can find the instance in your systray just like if Visual Studio ran it for you. To stop the server, right click on the icon in your systray and tell it to stop.
Note there are also Cassini batch files that you can use as well, but the basic auth tests will fail if using this server (which doesn't support basic http authentication).