README.md in acfs-0.14.0 vs README.md in acfs-0.15.0
- old
+ new
@@ -1,24 +1,20 @@
# Acfs - *API client for services*
[](http://badge.fury.io/rb/acfs) [](https://travis-ci.org/jgraichen/acfs) [](https://coveralls.io/r/jgraichen/acfs) [](https://codeclimate.com/github/jgraichen/acfs) [](https://gemnasium.com/jgraichen/acfs)
-Acfs is a library to develop API client libraries for single services within a
-larger service oriented application.
+Acfs is a library to develop API client libraries for single services within a larger service oriented application.
-Acfs covers model and service abstraction, convenient query and filter methods,
-full middleware stack for pre-processing requests and responses on a per service
-level and automatic request queuing and parallel processing. See Usage for more.
+Acfs covers model and service abstraction, convenient query and filter methods, full middleware stack for pre-processing requests and responses on a per service level and automatic request queuing and parallel processing. See Usage for more.
## Installation
Add this line to your application's Gemfile:
gem 'acfs', '~> 0.14.0'
-**Note:** Acfs is under development. I'll try to avoid changes to the public
-API but internal APIs may change quite often.
+**Note:** Acfs is under development. I'll try to avoid changes to the public API but internal APIs may change quite often.
And then execute:
$ bundle
@@ -40,12 +36,11 @@
use Acfs::Middleware::JsonDecoder
use Acfs::Middleware::MessagePackDecoder
end
```
-This specifies where the `UserService` is located. You can now create some
-models representing resources served by the `UserService`.
+This specifies where the `UserService` is located. You can now create some models representing resources served by the `UserService`.
```ruby
class User
include Acfs::Model
service UserService # Associate `User` model with `UserService`.
@@ -61,12 +56,11 @@
attribute :age, ::Acfs::Model::Attributes::Integer # Or use :integer
end
```
-The service and model classes can be shipped as a gem or git submodule to be
-included by the frontend application(s).
+The service and model classes can be shipped as a gem or git submodule to be included by the frontend application(s).
You can use the model there:
```ruby
@user = User.find 14
@@ -85,12 +79,11 @@
Acfs.run # Will request `http://users.myapp.org/users`
@users #=> [<User>, ...]
```
-If you need multiple resources or dependent resources first define a "plan"
-how they can be loaded:
+If you need multiple resources or dependent resources first define a "plan" how they can be loaded:
```ruby
@user = User.find(5) do |user|
# Block will be executed right after user with id 5 is loaded
@@ -139,10 +132,61 @@
@user.changed? # => false
@user.persisted? # => true
```
+## Stubbing
+
+You can stub resources in applications using an Acfs service client:
+
+```ruby
+# Enable stubs in spec helper
+Acfs::Stub.enable
+
+before do
+ Acfs::Stub.resource MyUser, :read, with: { id: 1 }, return: { id: 1, name: 'John Smith', age: 32 }
+ Acfs::Stub.resource MyUser, :read, with: { id: 2 }, raise: :not_found
+ Acfs::Stub.resource Session, :create, with: { ident: 'john@exmaple.org', password: 's3cr3t' }, return: { id: 'longhash', user: 1 }
+end
+
+it 'should find user number one' do
+ user = MyUser.find 1
+ Acfs.run
+
+ expect(user.id).to be == 1
+ expect(user.name).to be == 'John Smith'
+ expect(user.age).to be == 32
+end
+
+it 'should not find user number two' do
+ MyUser.find 3
+
+ expect { Acfs.run }.to raise_error(Acfs::ResourceNotFound)
+end
+
+it 'should allow stub resource creation' do
+ session = Session.create! ident: 'john@exmaple.org', password: 's3cr3t'
+
+ expect(session.id).to be == 'longhash'
+ expect(session.user).to be == 1
+end
+```
+
+By default Acfs raises an error when a non stubbed resource should be requested. You can switch of the behavior:
+
+```ruby
+before do
+ Acfs::Stub.allow_requests = true
+end
+
+it 'should find user number one' do
+ user = MyUser.find 1
+ Acfs.run # Would have raised Acfs::RealRequestNotAllowedError
+ # Will run real request to user service instead.
+end
+```
+
## Roadmap
* Update
* Better new? detection eg. storing ETag from request resources.
* Use PATCH for with only changed attributes and `If-Unmodifed-Since`
@@ -155,10 +199,9 @@
* Reusing model definitions for generating responses?
* Rails responders providing REST operations with integrated ETag,
Modified Headers, conflict detection, ...
* Pagination? Filtering? (If service API provides such features.)
* Messaging Queue support for services and models
- * Allow stubbing of resources as objects for testing services.
* Documentation
## Contributing
1. Fork it