= Caren API reference implementation

This is the reference implementation for the Caren CareProvider API (http://caren-cares.com). 

== Getting started

To get started you will need a care provider API private/public keypair.

* Generate a private key using: pk = Caren::Api.generate_private_key
* Extract the public key from it: pk.public_key
* Send the public key to info@caren-cares.com with an access request.
* Create an Api session and fill your private key and your care provider url (like https://example.caren-cares.com)

== Getting information from Caren

This implementation shows you how to get information from Caren. You can gather information about Links (linking your people to caren's),
care_providers (including updating your settings) and external_messages (chat messages between you and caren people).

== Providing information to Caren

Some information you can push to Caren (like updates to care_provider settings and new messages) using the basic API. 
Additionally Caren requires you to provide XML resources for People (search) and Events (daterange).
You can specify your API base url within your care_provider settings. You are required to implement the following resources:

* Finding a person by identifier: GET [BASE_URL]/people/?uid=[VALUE]
* Finding a list of events for a given person: GET [BASE_URL]/people/[EXTERNAL_ID]/events?from=[DATE]&to=[DATE]

The uid is your public customer number for this person, the external_id is your internal identifier (usually database id) for this person.
These urls should yield Caren compatible XML (the included Caren objects for Event and Person can generate that for you)

== Push notifications of changes from Caren

Caren supports a push link. Caren will regularly post a XML file with changes (Links, CareProviders, ExternalMessages) to any url.
Passing this XML and the corresponsing header signature into `Caren::Api.incoming` will yield the updated Caren objects.
You can optionally specify a push url within your care_provider settings.

== Contributing to caren-api
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
* Fork the project
* Start a feature/bugfix branch
* Commit and push until you are happy with your contribution
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Andre Foeken. See LICENSE.txt for
further details.