(Note: This page is currently locked from community editing.)
Overview
Introduction
Pownce has an Application Programming Interface (API) for anyone to create fun projects with Pownce.
Versioning
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.1/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.
JSON Callback Parameter
Developers may include an optional JavaScript callback parameter callback={callback} for JSON requests. The response will then be wrapped in the callback function. For example if I include the parameter callback=testFunction the response will look like testFunction(...);
Callback function names must start with a letter and are restricted to letters, numbers and underscores.
Cross Domain XML
Adobe Flash applications have permission to access the Pownce API and the cross domain XML file can be found at http://api.pownce.com/crossdomain.xml
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.1/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.1/public_note_lists.{format}
- request methods: GET
- required parameters:
- {format} The expected response format. Options are xml, or json.
- 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.
http://api.pownce.com/1.1/public_note_lists.xml?limit=10&page=2
User's Public Note List
- url: http://api.pownce.com/1.1/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.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.1/public_note_lists/for/dburka.json?type=links&page=2
Public Note
- url: http://api.pownce.com/1.1/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.
- show_replies={show_replies} By default the replies will not be included. To get the note with replies, use show_replies=true. Options are true or false.
- recipient_limit={recipient_limit} Number or recipients listed. Default is 0 and max is 100.
http://api.pownce.com/1.1/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.1/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.
- 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.1/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.1/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.1/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.1/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.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.1/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.
- ...?
