(Note: This page is currently locked from community editing.)

 

Overview Introduction Versioning Pagination Try It Out Help API Methods Notes Public Note List User's Public Note List Public Note Public Note Recipient List Users Profile Friends, Fans, and Fan Of Error Responses Coming Soon

 

Overview

 

Introduction

Pownce has an Application Programming Interface (API) for anyone to create fun projects with Pownce.

 

Versioning

 

• Current version: 1.0

Previous Versions

 

The API request URL has a version parameter which ensures compatibility when a new version of the Pownce API is released. If the version number is omitted from the URL, Pownce will assume the latest version of the API.

 

Pagination

It is up to Pownce application developers to decide how to paginate lists of items by using the limit={limit} and page={page} parameters. The first page is page 0. For example, if I like 5 friends per page and I want the 3rd page of friends for Daniel Burka, I would use: http://api.pownce.com/1.0/users/dburka/friends.xml?limit=5&page=2

 

If a particular page does not exist, a HTTP 404 error is returned and applications should handle this gracefully.

 

Try It Out

 

You can try all the API methods via a web browser or use the command-line tool, cURL. You probably already have cURL. Try getting Kevin Rose's public profile by typing the following into the command-line:

 

curl http://api.pownce.com/1.0/users/kevin.xml

 

Help

The easiest way to get help with the Pownce API is to check out our Google Group. Feel free to join and ask questions, suggest improvements, and collaborate on projects.

 

API Methods

 

Notes

 

Public Note List

• url: http://api.pownce.com/1.0/public_note_lists.{format}
• request methods: GET
• required parameters:
• {format} The expected response format. Options are xml, or json.
  • optional parameters:
• type={type} Filter the public notes by type. Options are messages, links, or events.
• limit={limit} Limit the number of notes returned. Default is 20 and max is 100.
• page={page} Page number.
  • example request: http://api.pownce.com/1.0/public_note_lists.xml?limit=10&page=2

 

 

User's Public Note List

• url: http://api.pownce.com/1.0/public_note_lists/{rel}/{username}.{format}
• request methods: GET
• required parameters:
• {rel} Options are for, from, or to.
  • for All public notes for the user (union of from and to).
  • from Public notes sent from the user.
  • to Public notes for the user from their friends not including notes the user has sent.
• {username} Username of a Pownce user.
• {format} The expected response format. Options are xml, or json.
  • optional parameters:
• type={type} Filter the public notes by type. Options are messages, links, or events.
• limit={limit} Limit the number of notes returned. Default is 20 and max is 100.
• page={page} Page number.
  • example request: http://api.pownce.com/1.0/public_note_lists/for/dburka.json?type=links&page=2

 

Public Note

• url: http://api.pownce.com/1.0/notes/{note_id}.{format}
• request methods: GET
• required parameters:
• {note_id} ID of the desired note.
• {format} The expected response format. Options are xml, or json.
  • optional parameters:
• show_replies={show_replies} By default the replies will be included. To get the note without replies, use show_replies=false. Options are true or false.
• recipient_limit={recipient_limit} Number or recipients listed. Default is 0 and max is 100.
  • example request: http://api.pownce.com/1.0/notes/2155.xml
  • notes: If the note is not public, a 403 Response Forbidden error will be returned.

 

Public Note Recipient List

• url: http://api.pownce.com/1.0/notes/{note_id}/recipients.{format}
• request methods: GET
• required parameters:
• {note_id} ID of the desired note.
• {format} The expected response format. Options are xml, or json.
  • optional parameters:
• limit={limit} Limit the number of recipients returned. Default is 20 and max is 100.
• page={page} Page number.
  • example request: http://api.pownce.com/1.0/notes/2155/recipients.xml?limit=15
  • notes: This endpoint should only be used if you would like to display a separate page of note recipients (without a note). If the note is not public, a 403 Response Forbidden error will be returned.

 

 

Users

 

Profile

• url: http://api.pownce.com/1.0/users/{username}.{format}
• request methods: GET
• required parameters:
• {username} Username of a Pownce user.
• {format} The expected response format. Options are xml, or json.
  • example request: http://api.pownce.com/1.0/users/dburka.xml
  • notes: Response fields may differ based on a member's privacy settings.

 

Friends, Fans, and Fan Of

• url: http://api.pownce.com/1.0/users/{username}/{relationship}.{format}
• request methods: GET
• required parameters:
• {username} Username of a Pownce user.
• {relationship} Options are friends, fans or fan_of.
  • friends Users who have a mutual relationship with this user.
  • fans Users who are fans of the user.
  • fan_of This user is a fan of these users.
• {format} The expected response format. Options are xml, or json.
  • optional parameters:
• limit={limit} Limit the number of users returned. Default is 20 and max is 100.
• page={page} Page number.
  • example request: http://api.pownce.com/1.0/users/dburka/friends.xml?page=2
  • notes:
• If the friends list is not public, a 403 Response Forbidden error will be returned. Applications should handle this gracefully.
• The list of friends is ordered alphabetically by first name. The fan list is unordered (for now).

 

Error Responses

 

Errors are returned in the same format as the request.

 

The response contains:

• status_code HTTP error response code.
• message Error message.
• request Request url that returned this error.

 

Coming Soon

• More response formats.
• Authentication via OAuth.
• APIs for posting notes.
• APIs for getting friends-only and private notes.
• ...?