Do The Green Thing: Users API

Home > Green Thing Labs > Users Api >

Users API

Authentication

To check authentication details and find out user details given an email/password, you can ask the API:

URL: http://www.dothegreenthing.com/session

Method: POST

The POST body should be an XML document. Both the Accept and Content-Type headers in the request should be set to "text/xml". An example document follows:

      <?xml version="1.0" encoding="UTF-8"?>
      <user>
        <email>test@example.com</email>
        <password>my_uber_secure_password</password>
      </user>

If the username and password are correct, the server will respond with 200 OK and a Location header specifying the location of the user's details (see next section). Note that this method does not provide any ongoing authentication - for calls which require authentication, the same details must be provided each time using HTTP Basic.

User Details

Details for each user are available in an XML format. An example is shown below:

URL: http://www.dothegreenthing.com/users/{username}.xml

Method: GET

Example: http://www.dothegreenthing.com/users/Floppy.xml

      <user href="http://www.dothegreenthing.com/users/Floppy">
        <name>Floppy</name>
        <avatar>
           <size_77>http://www.dothegreenthing.com/avatars/0000/0352/bug_tiny.png?1222690808</size_77>
           <size_44>http://www.dothegreenthing.com/avatars/0000/0352/bug_tiny_medium.png?1222690808</size_44>
           <size_26>http://www.dothegreenthing.com/avatars/0000/0352/bug_tiny_small.png?1222690808</size_26>
        </avatar>
        <num_views>364</num_views>
        <num_likes>421</num_likes>
        <num_comments>12</num_comments>
        <co2_saving>474</co2_saving>
        <created_at>2008-10-24T14:42:11Z</created_at>
        <following count="2">
          <user href="http://www.dothegreenthing.com/users/andyh">andyh</user>
          <user href="http://www.dothegreenthing.com/users/reddavis">reddavis</user>
        </following>
        <followers count="1">
          <user href="http://www.dothegreenthing.com/users/paperaeroplane">paperaeroplane</user>
        </followers>
      </user>

The tags provide the users avatar in three different sizes (77px, 44px and 26px). The avatars either come from Gravatar or from Green Thing itself, depending on whether the user has uploaded an avatar on GT or not.

The following tag lists the users that this user is following. The followers tag lists those users that are following this user. In the other data, "num_views" shows total number of views for this user's stories, num_likes shows number of times this user's stories have been "liked", and num_comments shows the number of comments this user's stories have received. co2_saving is the amount of co2 saved by this user, in kilograms.

Creating new users

To create a new user, you should send a POST request to the users URL:

URL: http://www.dothegreenthing.com/users

Method: POST

The POST body should be an XML document. Both the Accept and Content-Type headers in the request should be set to "text/xml". An example document and a description of each tag follows:

      <?xml version="1.0" encoding="UTF-8"?>
      <user>
        <email>test@example.com</email>
        <name>test</name>
        <password>my_uber_secure_password</password>
        <password-confirmation>my_uber_secure_password</password-confirmation>
      </user>

Tag	Description	Required?
Email	Email address of the user. This is the primary login key and must be unique across the site	Yes
Name	A unique username for the user. This is used in user URLs, and must be unique across the site	Yes
Password	The user's password	Yes
Password-Confirmation	The user's password again. We suggest that you don't fill this in automatically from the password setting, but ask the user to confirm the password themselves	Yes

If user creation is successful, the server will return "201 Created", and will include a Location header containing the URL of the new user's profile page. If there is an error in the submitted data, the server will return a 422 error, with error details returned in XML format in the body.

The following Ruby code creates a user through the API:

      #!/usr/bin/env ruby

      require 'net/http'
      require 'rubygems'
      require 'activesupport'

      # Create user
      user = {}
      user[:email] = "apitest@example.com"
      user[:name] = "apitest"
      user[:password] = "testing_the_api"
      user[:password_confirmation] = "testing_the_api"

      # Do HTTP POST
      url = URI.parse('http://www.dothegreenthing.com/users')
      req = Net::HTTP::Post.new(url.path)
      req['Accept'] = "text/xml"
      req['Content-Type'] = "text/xml"
      req.body = user.to_xml :root => "user"
      http = Net::HTTP.new(url.host, url.port)
      http.set_debug_output($stdout)
      res = http.start do |x|
        x.request(req)
      end
      case res
        when Net::HTTPSuccess, Net::HTTPRedirection
          puts "Created user OK at #{res['Location']}"
        else
          res.error!
      end

Updating Details

Some user details can be updated through the API. Currently only email and password changes are supported, though more functionality will be forthcoming in future as it is added to the main website.

URL: http://www.dothegreenthing.com/profile/{username}/update_user_settings

Method: PUT

Example: http://www.dothegreenthing.com/profile/Floppy/update_user_settings

The PUT body should be an XML document. Both the Accept and Content-Type headers in the request should be set to "text/xml". An example document and a description of each tag follows:

      <?xml version="1.0" encoding="UTF-8"?>
      <user>
        <email>me@newemail.example.com</email>
        <password>newpassword</password>
        <password-confirmation>newpassword</password-confirmation>
      </user>

Tag	Description	Required?
Email	Email address of the user. This is the primary login key and must be unique across the site	No
Name	A unique username for the user. This is used in user URLs, and must be unique across the site	No
Password	The user's password	No
Password-Confirmation	The user's password again. We suggest that you don't fill this in automatically from the password setting, but ask the user to confirm the password themselves	Only if the password is present

If the update is successful, the server will return "200 OK". If there is an error in the submitted data, the server will return a 422 error, with error details returned in XML format in the body.

The following Ruby code updates a user's settings through the API:

      #!/usr/bin/env ruby

      require 'net/http'
      require 'rubygems'
      require 'activesupport'

      GT_EMAIL = "email_goes_here"
      GT_USERNAME = "username_goes_here"
      GT_PASSWORD = "password_goes_here"

      # Create preferences
      user = {}
      user[:email] = "me@newemail.example.com"
      user[:password] = "new_password"
      user[:password_confirmation] = "new_password"

      # Do HTTP PUT
      url = URI.parse("http://www.dothegreenthing.com/profile/#{GT_USERNAME}/update_user_settings")
      req = Net::HTTP::Put.new(url.path)
      req.basic_auth GT_EMAIL, GT_PASSWORD
      req['Accept'] = "text/xml"
      req['Content-Type'] = "text/xml"
      req.body = user.to_xml :root => "user"
      http = Net::HTTP.new(url.host, url.port)
      http.set_debug_output($stdout)
      res = http.start do |x|
        x.request(req)
      end
      case res
        when Net::HTTPSuccess
          puts "Updated settings OK"
        else
          res.error!
      end

Forgotten password

The API includes the ability to request a password reset:

URL: http://www.dothegreenthing.com/users/forgot_password

Method: POST

The POST body should be an XML document. Both the Accept and Content-Type headers in the request should be set to "text/xml". An example document and a description of each tag follows:

      <?xml version="1.0" encoding="UTF-8"?>
      <user>
        <email>apitest@example.com</email>
      </user>

Tag	Description	Required?
Email	Email address of the user	Yes

If the request is successful, the server will return "200 OK" and the user will be emailed a link to use to reset their password through the main website. If the email was not recognised, a "400 Bad Request" will be returned.

The following Ruby code requests a password reset through the API:

      #!/usr/bin/env ruby

      require 'net/http'
      require 'rubygems'
      require 'activesupport'

      # Create user
      user = {}
      user[:email] = "apitest@example.com"

      # Do HTTP POST
      url = URI.parse('http://localhost:3000/users/forgot_password')
      req = Net::HTTP::Post.new(url.path)
      req['Accept'] = "text/xml"
      req['Content-Type'] = "text/xml"
      req.body = user.to_xml :root => 'user'
      http = Net::HTTP.new(url.host, url.port)
      http.set_debug_output($stdout)
      res = http.start do |x|
        x.request(req)
      end
      case res
        when Net::HTTPSuccess
          puts "OK: password will be sent to user"
        else
          res.error!
      end

Following users

To follow a user, you should send an [wiki:APIDetails#Authentication authenticated] POST request to the user's "followers" URL:

URL: http://www.dothegreenthing.com/users/{username}/followers

Method: POST

The POST body should be empty. Both the Accept and Content-Type headers in the request should be set to "text/xml". A 201 Created should be returned, with a Location header specifying the resource URL for the relationship.

You can stop following a user by sending a DELETE request to URL for the relationship (as returned by the POST above).

URL: http://www.dothegreenthing.com/users/{username}/followers/{your-username}

Method: DELETE

An empty 200 OK response will be returned if the relationship was removed.

The following Ruby code demonstrates how to follow and stop following a user.

      #!/usr/bin/env ruby

      require 'net/http'
      require 'rubygems'
      require 'activesupport'

      GT_EMAIL = "email_goes_here"
      GT_PASSWORD = "password_goes_here"
      USERNAME_TO_FOLLOW = ARGV[0]

      # Do HTTP PUT to followers to follow a user
      url = URI.parse("http://www.dothegreenthing.com/users/#{USERNAME_TO_FOLLOW}/followers")
      req = Net::HTTP::Post.new(url.path)
      req.basic_auth GT_EMAIL, GT_PASSWORD
      req['Accept'] = "text/xml"
      req['Content-Type'] = "text/xml"
      http = Net::HTTP.new(url.host, url.port)
      http.set_debug_output($stdout)
      res = http.start do |x|
        x.request(req)
      end
      location = res['Location']
      case res
        when Net::HTTPSuccess, Net::HTTPRedirection
          puts "You are now following #{USERNAME_TO_FOLLOW} - URL: #{location}"
        else
          res.error!
      end

      # Do HTTP DELETE to follower URL to stop following
      url = URI.parse("http://www.dothegreenthing.com#{location}")
      req = Net::HTTP::Delete.new(url.path)
      req.basic_auth GT_EMAIL, GT_PASSWORD
      req['Accept'] = "text/xml"
      req['Content-Type'] = "text/xml"
      http = Net::HTTP.new(url.host, url.port)
      http.set_debug_output($stdout)
      res = http.start do |x|
        x.request(req)
      end
      case res
        when Net::HTTPSuccess, Net::HTTPRedirection
          puts "You are now not following #{USERNAME_TO_FOLLOW}"
        else
          res.error!
      end

BACK TO TOP Chevron

Green Thing Latest

Latest To Join

	foxinthebox
	smithgrace
	raheelas786