(Below is an outline. Details forthcoming...)

The initial release of the user service API is listed below. Any mention of a URI path is expected to be  qualified with the final productioon or integration URI of http://user.bsgplatform.com or usertest.bsgplatform.com, respectively). All calls to any resource requires that the http_authorization header be set (we're using Basic authentication). 

Common HTTP Status Code responses (any response statuses that are different/expanded from these, inluding payloads, are detailed in the individual api method sections)

200 Ok

401 Unauthorized

404 Not Found

415 Unsupported Media Type

409 Conflict

500 Server Error

503 Service Unavailable 

Retrieving/Creating users

GET /users/emailhash.xml (TODO /users/guid.xml)

• Returns an xml representation of a user. An example format follows. The method expects a hash of the email (as part of the resource name) and the users' password as part of the query string. [srb] What kind of hash?  MD5?  Is there something in ruby I can call to get the right kind of hash?
• <user>
    <created_at>2007-11-08T15:02:22-06:00</created_at>
    <email>tech-support@kalivo.com</email>
    <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
    <updated_at>2007-11-09T16:04:58-06:00</updated_at>
    <active_persona>
      <company_name>BSG Alliance, yo</company_name>
      <created_at>2007-03-23T14:17:56-05:00</created_at>
      <display_name>BSG Support</display_name>
      <full_name></full_name>
      <ip></ip>
      <job_title>Technical Support, yo</job_title>
      <updated_at>2007-11-09T16:04:58-06:00</updated_at>
      <uri>http://www.bsgalliance.yo</uri>
    </active_persona><activated_at></activated_at>
  <is_banned>false</is_banned>
  <about_me>i am fancy.</about_me>
  <yahoo_name></yahoo_name>
  <activation_code></activation_code>
  <aim_name></aim_name>
  <id>1</id>
  <rank></rank>
  <has_avatar>false</has_avatar>
  <password></password>
  <jabber_name></jabber_name>
  </user>

[srb] I'm surprised to not see some of these fields grouped as ~ <attributes/> and just a bunch of name/value pairs (e.g. jabbar_name or aim_name) ?

POST /users.xml

• Creates new user. An xml representation of the user is expected as an input parameter (paramater name is 'user'). The xml representation is returned as part of the 200 OK response. If the user can not be created, the xml representation is returned along with a collection of error messages.  [srb] Shouldn't this be 201 Created ?
• An example is below:

<user>
  <created_at>2007-11-05T10:59:02-06:00</created_at>
  <email>iampeakoiltheory@gmail.com</email>  <updated_at>2007-11-05T11:01:02-06:00</updated_at><errors>
  <error>User personas is invalid</error>
</errors>
</user>

[srb] Where's the GUID?

PUT /users/emailhash.xml (TODO /users/guid.xml)

• Update a user profile. The service takes a parameter named 'user' that is an xml representation of the user and the updated profile. The xml representation is returned along with the 200 OK status response.  A 409 conflict status is returned is the user attempts to change their email to an already existing one. Any other error returns the user xml representation along with a collection of errors 
• [srb] Think we want some discussion of personas here...

TODO: DELETE /users/emailhash.xml

[srb] TODO: DELETE /users/guid

Importing users (Bulk create)

POST /user_imports.xml

• Bulk creation of users. Service expects a list of users in xml format. Example below    <users>
      <user>
  <salt/>
  <last_login_at/>
  <job_title>Technical Support, yo</job_title>
  <uri>http://www.bsgalliance.yo</uri>
  <updated_at>2007-11-09T16:03:57-06:00</updated_at>
  <is_banned>false</is_banned>
  <activated_at/>
  <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
  <crypted_password/>
  <company_name>BSG Alliance, yo</company_name>
  <yahoo_name/>
  <previous_last_login_at/>
  <num_of_logins>0</num_of_logins>
  <about_me/>
  <activation_code/>
  <rank/>
  <password_reset_code/>
  <id>1</id>
  <aim_name/>
  <immutable>false</immutable>
  <ip/>
  <has_avatar>false</has_avatar>
  <display_name>BSG Support</display_name>
  <full_name/>
  <deletable>true</deletable>
  <jabber_name/>
  <email>tech-support@kalivo.com</email>
  <created_at>2007-03-23T14:17:56-05:00</created_at>
  </user>
  <user>
  <salt>f7549d346b3613952b8ae31467f3855a4eacb071</salt>
  <last_login_at/>
  <job_title/>
  <uri>http://www.kalivo.com</uri>
  <updated_at>2007-03-23T14:17:59-05:00</updated_at>
  <is_banned>false</is_banned>
  <activated_at>2006-07-18T17:27:26-05:00</activated_at>
  <guid/>
  <crypted_password>026dd03e5b00e4a56807792200bb3ddc2763ac3b</crypted_password>
  <company_name>Kalivo</company_name>
  <yahoo_name/>
  <previous_last_login_at/>
  <num_of_logins>0</num_of_logins>
  <about_me/>
  <activation_code>59c31e4b6d5c915bc3e0ce00a28d197db8cb226a</activation_code>
  <rank>Member</rank>
  <password_reset_code/>
  <id>2</id>
  <aim_name/>
  <immutable>true</immutable>
  <ip/>
  <has_avatar>false</has_avatar>
  <display_name>Anonymous User</display_name>
  <full_name/>
  <deletable>false</deletable>
  <jabber_name/>
  <email>anonymous@kalbsgivo.com</email>
  <created_at>2007-03-23T14:17:59-05:00</created_at>
  </user></users>
• Any fields passed to the service that are not required are stored as additional attributes
• Return response includes a body element that describes detailof the export including any failed users with a reason as to their failure. Example below.
• <import_details>
  <user_import>
    <created_at>2007-11-11T17:54:47-06:00</created_at>
    <domain>http://localhost:3000</domain>
    <failure_count>4</failure_count>
    <ip>127.0.0.1</ip>
    <success_count>152</success_count>
  </user_import>
  <failures>
  <user>
    <created_at>2007-11-08T15:02:22-06:00</created_at>
    <email>tech-support@kalivo.com</email>
    <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
    <updated_at>2007-11-09T16:04:58-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
   </user>
  <user>
    <created_at>2007-11-05T10:59:02-06:00</created_at>
    <email>iampeakoiltheory@gmail.com</email>
    <guid></guid>
    <updated_at>2007-11-05T11:01:02-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
  </user>
  <user>
    <created_at>2007-11-08T00:21:32-06:00</created_at>
    <email>iampeakoiltheory2@gmail.com</email>
    <guid>d947de90-8dc2-11dc-85f3-001b7744e275</guid>
    <updated_at>2007-11-08T00:21:33-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors> 
  </user>
  <user>
    <created_at>2007-11-08T15:49:08-06:00</created_at>
    <email>mike@roeder.com</email>
    <guid>6f29efd0-8e44-11dc-b7c6-0019d1039198</guid>
    <updated_at>2007-11-08T15:50:46-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
   </user>
  </failures>
  </import_details>

TODO: PUT /user_imports.xml (Bulk update users)