Permalink
Browse files

readme edit

  • Loading branch information...
1 parent 8f03eaa commit a709b8640d57d175fd0f3d5bd09bd1e993d34868 Robert Sosinski committed Jan 23, 2010
Showing with 73 additions and 59 deletions.
  1. +73 −59 README → README.markdown
View
@@ -1,102 +1,111 @@
-= Summary
+Summary
+=======
-Authenticator (originally called Capansis Authentication) is a web service that allows you to easily
+Authenticator is a web service that allows you to easily
implement a very secure and robust authentication system into your application. It provides a fully
RESTful API using XML over HTTP and is secured using HTTP Basic Authentication. This document
describes how to interact with the Authenticator service using cURL and ActiveRecord.
Throughout this document, you will see code examples. There will always be two, first a cURL
example, followed by an ActiveResource example.
- How to interact with Capansis Authentication using cURL
+ How to interact with Authenticator using cURL
- How to interact with Capansis Authentication using ActiveResource
+ How to interact with Authenticator using ActiveResource
-= Site Domain and API Key
+Site Domain and API Key
+=======================
-In order to incorporate Capansis Authentication into your application, you will first need a valid
+In order to incorporate Authenticator into your application, you will first need a valid
domain and API key, such as:
-Domain: capansis.com
+Domain: `capansis.com`
-API Key: c144dccfa6d57711185083fb0336dcfa9b33ac61
+API Key: `c144dccfa6d57711185083fb0336dcfa9b33ac61`
These credentials can then be used as a username and password with HTTP Basic Authentication to
interface your application with the authentication service.
- http(s)://capansis.com:c144dccfa6d57711185083fb0336dcfa9b33ac61@authentication.capansis.net
+ http(s)://capansis.com:c144dccfa6d57711185083fb0336dcfa9b33ac61@authentication.capansis.net
- self.site = "http(s)://authentication.capansis.net"
- self.user = "capansis.com"
- self.password = "c144dccfa6d57711185083fb0336dcfa9b33ac61"
+ self.site = "http(s)://authentication.capansis.net"
+ self.user = "capansis.com"
+ self.password = "c144dccfa6d57711185083fb0336dcfa9b33ac61"
-= Making Requests
+Making Requests
+===============
Requests to the authentication service are made via URLs and HTTP verbs. The URL represents a
resource within the authentication service (e.g. an account), while the HTTP verb describes method
to interact with it (e.g. retrieve, add, change or delete). There are four different verbs you can
use to interact with the authentication service.
-*Get*: Retrieves a object or collection of objects from the authentication service, such as a users
+__Get__: Retrieves a object or collection of objects from the authentication service, such as a users
account.
-*Post*: Adds a new object to the system, such as registering a new user or logging an existing user
+__Post__: Adds a new object to the system, such as registering a new user or logging an existing user
into the system.
-*Put*: Changes an existing object within the system, such as a user updating their email address or
+__Put__: Changes an existing object within the system, such as a user updating their email address or
changing their password.
-*Delete*: Removes an object from the system.
+__Delete__: Removes an object from the system.
These methods are used to interact with two objects via the API.
-== Account
+Account
+-------
Represents the account for a user. An account contains the users email address and encrypted
password.
-== Login
+Login
+-----
Represents the authenticated session for a user. A login contains the time and date that a user
successfully authenticated via the service.
-= Accounts
+Accounts
+========
There are seven ways to interact with the Account resource API.
-== Getting a Collection of Accounts
+Getting a Collection of Accounts
+--------------------------------
To get a full collection of accounts, filtered by the first letter in an accounts email address,
pass a GET request to the Accounts resource with the letter parameter.
- curl -X GET -i -u domain:api_key http(s)://authentication.capansis.com/accounts.xml?letter=a
+ curl -X GET -i -u domain:api_key http(s)://authentication.capansis.com/accounts.xml?letter=a
- Account.find(:all, :params => {:letter => "a"})
+ Account.find(:all, :params => {:letter => "a"})
-*NOTE*:
+__NOTE__:
-If no letter parameter is given, Capansis Authentication will default to the letter "a".
+If no letter parameter is given, Authenticator will default to the letter "a".
-== Getting a Single Account
+Getting a Single Account
+------------------------
To get a single account, pass a GET request to an Accounts resource member.
- curl -X GET -i -u domain:api_key http(s)://authentication.capansis.com/accounts/12345.xml
+ curl -X GET -i -u domain:api_key http(s)://authentication.capansis.com/accounts/12345.xml
- Account.find(12345)
+ Account.find(12345)
-== Creating a New Account
+Creating a New Account
+----------------------
To create a new account, pass a POST request to the Accounts resource with properly formated account
data.
- curl -X POST -i -u domain:api_key \
- -d "account[email_address]=name@domain.com&account[password]=password&account[password_confirmation]=password" \
- http(s)://authentication.capansis.com/accounts.xml
+ curl -X POST -i -u domain:api_key \
+ -d "account[email_address]=name@domain.com&account[password]=password&account[password_confirmation]=password" \
+ http(s)://authentication.capansis.com/accounts.xml
- @account = Account.new(params[:account])
- @account.save
+ @account = Account.new(params[:account])
+ @account.save
If the new account can be created, the authentication service will return the XML representation of
the account.
@@ -108,76 +117,81 @@ After successful creation, the authentication service will send a verification l
address registered. This letter will include a verification link, that once clicked, will activate
the account and log the user into the system.
-*NOTE*:
+__NOTE__:
Users will not be able to login through the authentication service until their account is activated.
-== Verifying an Accounts Email Address
+Verifying an Accounts Email Address
+-----------------------------------
To activate or recover an account, pass a PUT request to an Accounts resource member with a
verification key.
- curl -X PUT -i -u domain:api_key http(s)://authentication.capansis.net/accounts/12345.xml?verification_key=6a57a7d7430418b3fb579c9c7558ec2719aa9edb37b6940a381d72af16c3619e
+ curl -X PUT -i -u domain:api_key http(s)://authentication.capansis.net/accounts/12345.xml?verification_key=6a57a7d7430418b3fb579c9c7558ec2719aa9edb37b6940a381d72af16c3619e
- @account = Account.find(12345)
- @account.put(:verify, :verification_key => "6a57a7d7430418b3fb579c9c7558ec2719aa9edb37b6940a381d72af16c3619e")
+ @account = Account.find(12345)
+ @account.put(:verify, :verification_key => "6a57a7d7430418b3fb579c9c7558ec2719aa9edb37b6940a381d72af16c3619e")
If the account and verification key are valid, the authentication service will return a HTTP 200 OK.
Otherwise, it will return a HTTP 404 Not Found.
-*NOTE*:
+__NOTE__:
You can check if the Account is being activated or recovered by checking the activated attribute.
This is helpful if you want activating users to be redirected to a "Home" page, while recovering
users to be redirected to a "Change Password" page.
- # Example using ActiveResource
+ # Example using ActiveResource
- # If the verification is for an activation
- @account.activated? => false
- # If the verification is for a recovery
- @account.activated? => true
+ # If the verification is for an activation
+ @account.activated? => false
+ # If the verification is for a recovery
+ @account.activated? => true
-== Updating an Existing Account
+Updating an Existing Account
+----------------------------
To update account, pass a PUT request to an Accounts resource member with properly formatted account
data.
- curl -X PUT -i -u domain:api_key \
- -d "account[email_address]=name@domain.com&account[password]=password&account[password_confirmation]=password" \
- http(s)://authentication.capansis.com/12345/accounts.xml
+ curl -X PUT -i -u domain:api_key \
+ -d "account[email_address]=name@domain.com&account[password]=password&account[password_confirmation]=password" \
+ http(s)://authentication.capansis.com/12345/accounts.xml
- @account = Account.find(12345).load(params[:account])
- @account.save
+ @account = Account.find(12345).load(params[:account])
+ @account.save
If the account can be updated, the authentication service will return the XML representation of the
account.
If the account cannot be updated, the authentication service will return an HTTP 422 Unprocessable
Entity code and an XML representation of the errors.
-== Recovering an Existing Account
+Recovering an Existing Account
+------------------------------
To have a recovery letter with verification link sent to an account owners email address of record,
pass a POST request to the Accounts resource with an email address.
- curl -X POST -i -u domain:api_key -d "email_address=name@domain.com" http(s)://authentication.capansis.net/accounts/recover.xml
+ curl -X POST -i -u domain:api_key -d "email_address=name@domain.com" http(s)://authentication.capansis.net/accounts/recover.xml
- Account.post(:recover, :email_address => name@domain.com)
+ Account.post(:recover, :email_address => name@domain.com)
If the account can be found, the authentication service will send an email to the address on record,
thus allowing the account owner to login via the verify action.
-= Logins
+Logins
+======
There is one way to interact with the Account resource API.
-== Creating a new Login
+Creating a new Login
+--------------------
To verify an accounts credentials and create a new Login, pass a POST request to the Logins resource
with properly formated login data.
- curl -X POST -i -u domain.com:api_key -d "login[email_address]=name@domain.com&login[password]=secret" http(s)://authentication.capansis.net/logins.xml
+ curl -X POST -i -u domain.com:api_key -d "login[email_address]=name@domain.com&login[password]=secret" http(s)://authentication.capansis.net/logins.xml
- @login = Login.new(params[:login])
- @login.save
+ @login = Login.new(params[:login])
+ @login.save

0 comments on commit a709b86

Please sign in to comment.