=============================
REST API
=============================

This REST API is a work in progress.
It implements access to entities of OBM database without using the UI interface.

At october, 2007, only contacts and companies are accessibles.

!! WARNING !!

There's no access control, with this API you have access to all items without usual restrictions.
The user used to access the data is the superadmin.



=============================
Prerequisites
=============================

Apache module mod_rewriting installed and active. (tests done with apache 2.2)
OBM 2.0.3 or newer.



=============================
Install
=============================

Apache rewrite rules (in OBM virtual host)

RewriteEngine    On
RewriteLog       "/var/log/apache2/rewrite.log"
RewriteRule  ^/rest/([^/]*)/search/(.*)   /rest/index.php?entity=$1&action=search&$2 [L]
RewriteRule  ^/rest/([^/]*)(/(.*))?$      /rest/index.php?entity=$1&entity_id=$3     [L]

PHP files

Please put the entire rest directory inside the /path/to/obm/php/ tree.
Copy the config.inc.sample to config.inc and modify the config.inc if necessary.



=============================
Use it
=============================

The URL are : 

 - for the list
   http://www.domain.tld/obm/rest/<entity> 
   ex. : http://www.mydomain.com/obm/rest/contact

 - for the detail
   http://www.domain.tld/obm/rest/<entity>/<entity_id> 
   ex. : http://www.mydomain.com/obm/rest/contact/2

 - for a search
   http://www.domain.tld/obm/rest/<entity>/search/<query> 
   ex. : http://www.mydomain.com/obm/rest/contact/search/firstname=Roger&town=Paris

 - for a multi-search
   http://www.domain.tld/obm/rest/<entity>/search/<query> 
   ex. : http://www.mydomain.com/obm/rest/contact/search/firstname=Roger|Robert&town=Paris

 - for a multi-search with only some field 
   http://www.domain.tld/obm/rest/<entity>/search/<query> 
   ex. : http://www.mydomain.com/obm/rest/contact/search/firstname=Roger|Paul&town=Paris&require_fields=contact_firstname|contact_lastname
  
  

========================================================
Allowed parameters for multi-parameters search 
========================================================
company search parameters

	name
	number
	phone
	zip
	town
	country
	type
	activity
	datasource
	market
	date_after
	date_before
	naf

contact search parameters 

	firstname
	lastname
	archive
	number
	phone
	email
	company
	zip
	town
	country
	datasource
	function
	title
	market
	date_type
	date_after
	date_before

========================================================
Allowed field for multi-parameters search 
========================================================

contact view field 

  contact_id
  contact_function
  contact_firstname
  contact_lastname
  contact_genre
  contact_title
  contact_office
  contact_address1
  contact_address2
  contact_address3
  company_town
  company_zipcode
  company_country
  company_phone
  company_fax
  contact_email

company view field 

  company_id
  company_name
  company_number
  company_isin
  company_address1
  company_address2
  company_address3
  company_town
  company_zipcode
  company_country
  company_phone
  company_fax
  company_web

=============================
Tech notes
=============================

index.php is the main file. It receives the requests, call the functions and send back the correct http header and xml.

config.inc sets some paths and parameters

contact.php and company.php are similar
	get_contact_list_ids queries the database
	get_contact_list constructs the xml list of all contacts
	get_contact_detail_by_id queries the database and manage a translation between db field and wml field names
	get_contact_detail constructs the xml detail listing for one contact
	get_contact_search replacement of fields in obm fields
	get_contact_mono_search use the search function of OBM framework


