View
 

API Documentation2-0

This is the current version of the API. Older versions may be found here.

 

(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

 

    • Current version: 2.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.

 

Authentication

To access private data or post a note via the Pownce API, developers will need to authenticate the Pownce user. There are currently two methods for authenticating users for the Pownce API: Http Basic Authentication and OAuth.

 

Registering an Application

First, developers must register their application via the Pownce website. It is possible to edit application information at any time, and the application won't appear in the application directory until published.

 

Register your application: http://pownce.com/api/apps/new/

View all your applications: http://pownce.com/api/apps/

 

Http Basic Authentication

Developers will need to construct and send the appropriate authorization header. To construct the header:

  • append the username and password like username:password
  • base-64 encode the username:password
  • send the "Authorization" header with the value "Basic x" where x is the base-64 encoded username:password

 

See: Http Basic Authentication

 

With each Http Basic authenticated request, the parameter app_key must also be included. The app_key is the application key assigned when the application was registered.

 

OAuth Authentication

OAuth is so hot right now and the Pownce API has it.

 

    • request token url: http://api.pownce.com/2.0/oauth/request_token
    • user authorization url: http://api.pownce.com/2.0/oauth/authorize
    • access token url: http://api.pownce.com/2.0/oauth/access_token
    • signature methods: HMAC-SHA1
    • request token expiration: 1 day
    • access token expiration: never

 

Your oauth_consumer_key and oauth_consumer_secret are your application key and application secret assigned when you registered your application. The app_key parameter is not required since each OAuth request must contain the oauth_consumer_key.

 

See: OAuth website, OAuth documentation

 

Authentication Help

If you are having trouble with authentication please post a message to the Google Group.

 

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/2.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.

 

Rate Limiting / Throttling

 

The API currently has no limit on the number of requests applications can make. Please be kind to the API so we can keep it that way and try to use the minimum number of requests to accomplish a task. If you need help figuring out how to efficiently perform a task, feel free to ask in the Google Group.

 

Posting notes does have a rate limit per user. Each user may post 20 notes every 10 minutes (average 2 per minute) and no more than 300 notes per day. This limit is to prevent spammers and friend-annoyers.

 

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/2.0/users/kevin.xml

 

Test out authentication by verifying the authorized user.

 

curl -H "Authorization: basic {encoded}" "http://api.pownce.com/2.0/auth/verify.xml?app_key={app_key}"

 

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.

 

Is there something you want from the Pownce API that you can't seem to find? Try posting to the Google Group with the information you'd like from the API. More API endpoints WILL be added to the API depending on input from developers like you.

 

API Methods

 

Notes

 

Public Note List

Get a list of all recent public notes.

    • url: http://api.pownce.com/2.0/note_lists.{format}
    • request methods: GET
    • authentication: None
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
    • optional url 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. Starts at 0.
  • since_id={since_id} Limit the notes returned to those greater than the specified note id.
    • example request: http://api.pownce.com/2.0/note_lists.xml?limit=10&page=2
    • notes:
  • This endpoint replaces the public note list endpoint from previous versions.

 

Note List

Get a list of notes for a user. To get your "inbox" of notes, the typical Pownce stream, you'll need to call this method with your own username and proper authentication. An authenticated call with a friend's username will return all the notes that they've sent you (public and private). Without authentication, this method returns a list of public notes sent by the user.

    • url: http://api.pownce.com/2.0/note_lists/{username}.{format}
    • request methods: GET
    • authentication: None, HTTP basic, OAuth
    • required url parameters:
  • {username} Username of a Pownce user.
  • {format} The expected response format. Options are xml, or json.
    • required parameters (HTTP basic authenticated user):
  • {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
    • optional url parameters:
  • type={type} Filter the notes by type. Options are messages, links, or events. Authenticated users may also filter by files.
  • limit={limit} Limit the number of notes returned. Default is 20 and max is 100.
  • page={page} Page number. Starts at 0.
  • since_id={since_id} Limit the notes returned to those greater than the specified note id.
    • optional url parameters (authenticated user):
  • filter={filter} Get a subset of the authenticated user's note list. Options are notes (no replies), replies, sent, public, private, nonpublic (private and friends-only notes), and all. If no filter is specified, the notes will be returned according to the user's preferences.
  • set={set_id} Filter the authenticated user's notes by a particular set. Only available for the authenticated user's own notes.
    • example requests:
  • http://api.pownce.com/2.0/note_lists/dburka.json?type=links&page=2 Links for dburka, page 3.
  • http://api.pownce.com/2.0/note_lists/ariel.xml?type=messages&filter=sent&limit=1 Latest message by ariel.
  • http://api.pownce.com/2.0/note_lists/leahculver.json?set=13613 My notes, filtered by one of my sets.
    • notes:
  • A list of public notes will be returned for any non-authenticated user. This endpoint replaces the user's public note list endpoint from previous versions. To get the authenticated user's public notes, use filter=public.
  • For a friend of the authenticated user, this method will return notes sent by that friend including private and friends-only notes.

 

Note

Get a particular note by id.

    • url: http://api.pownce.com/2.0/notes/{note_id}.{format}
    • request methods: GET
    • authentication: None, HTTP basic, OAuth
    • required url parameters:
  • {note_id} ID of the desired note.
  • {format} The expected response format. Options are xml, or json.
    • required url parameters (HTTP basic authenticated user):
  • {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
    • optional url parameters:
  • 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.
    • example request: http://api.pownce.com/2.0/notes/2155.xml
    • notes:
  • If the note is not public or not viewable to the authenticated user, a 403 Response Forbidden error will be returned.

 

Note Recipient List

Get a list of recipients for a particular note.

    • url: http://api.pownce.com/2.0/notes/{note_id}/recipients.{format}
    • request methods: GET
    • authentication: None, HTTP basic, OAuth
    • required url parameters:
  • {note_id} ID of the desired note.
  • {format} The expected response format. Options are xml, or json.
    • required url parameters (HTTP basic authenticated user):
  • {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
    • optional url parameters:
  • limit={limit} Limit the number of recipients returned. Default is 20 and max is 100.
  • page={page} Page number. Starts at 0.
    • example request: http://api.pownce.com/2.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 or not viewable to the authenticated user, a 403 Response Forbidden error will be returned.

 

Users

 

Profile

Get an individual user's profile information.

    • url: http://api.pownce.com/2.0/users/{username}.{format}
    • request methods: GET
    • authentication: None, HTTP basic, OAuth
    • required url parameters:
  • {username} Username of a Pownce user.
  • {format} The expected response format. Options are xml, or json.
    • required url parameters (HTTP basic authenticated user):
  • {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
    • example request: http://api.pownce.com/2.0/users/dburka.xml
    • notes:
  • Response fields may differ based on a member's privacy settings and if they are authenticated.

 

Friends, Fans, and Fan Of

Get an individual user's relationship data.

    • url: http://api.pownce.com/2.0/users/{username}/{relationship}.{format}
    • request methods: GET
    • authentication: None, HTTP basic, OAuth
    • required url 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.
    • required url parameters (HTTP basic authenticated user):
  • {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
    • optional url parameters:
  • limit={limit} Limit the number of users returned. Default is 20 and max is 100.
  • page={page} Page number. Starts at 0.
    • example request: http://api.pownce.com/2.0/users/dburka/friends.xml?page=2
    • notes:
  • If the friends list is not public or not viewable by the authenticated user, 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).

 

Auth

 

Verify Auth

Check that authentication is successful. This endpoint can be used to either test if the Http Basic auth header is correct or if your request has a valid OAuth access token.

    • url: http://api.pownce.com/2.0/auth/verify.{format}
    • request methods: GET
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.

 

Posting

 

Send To List

Get a the list of potential recipients for the authenticated user. Includes options for the public, all friends, sets, and individual friends.

    • url: http://api.pownce.com/2.0/send/send_to.{format}
    • request methods: GET
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • notes:
  • The selected parameter that is returned is the user's preference for their default "send to" option and developers should respect this preference.
  • The list of potential recipients is unordered.
  • Files cannot be sent to "the public" so you should gracefully omit this option when the user goes to post a file.

 

Post a Message

Post a note that contains only a message.

    • url: http://api.pownce.com/2.0/send/message.{format}
    • request methods: POST
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • required POST parameters:
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
  • {note_body} The main text body of the note.
    • notes:
  • Returns the note that was posted in the requested response format.

 

Post a Link

Post a note that contains a link.

    • url: http://api.pownce.com/2.0/send/link.{format}
    • request methods: POST
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • required POST parameters:
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
  • {url} The full url for the link. Ex: http://pythong.org
    • optional POST parameters:
  • {note_body} The main text body of the note.
    • notes:
  • Returns the note that was posted in the requested response format.

 

Post an Event

Post a note that contains an event.

    • url: http://api.pownce.com/2.0/send/event.{format}
    • request methods: POST
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • required POST parameters:
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
  • {event_name} Name of the event.
  • {event_location} Location of the event.
  • {event_date} Date of the event in the format YYYY-MM-DD hh:mm. Ex: 2008-01-16 20:00
    • optional POST parameters:
  • {note_body} The main text body of the note.
    • notes:
  • Returns the note that was posted in the requested response format.
  • Event date seconds will be ignored.

 

Post a File

Post a note that contains a file.

    • url: http://api.pownce.com/2.0/send/file.{format}
    • url (pro users): http://api.pownce.com/2.0/send/file_pro.{format}
    • request methods: POST
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • required POST parameters:
  • {note_to} The recipient(s) of the note. Options are all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
  • {media_file} The data of the file.
    • optional POST parameters:
  • {note_body} The main text body of the note.
    • notes:
  • Returns the note that was posted in the requested response format.
  • Users with pro accounts may upload larger files. Please use the url http://api.pownce.com/2.0/send/file_pro.{format} for pro user file uploads.
  • The file size limit will be respected server-side, so please make the limit clear to users.
  • For OAuth requests, put the OAuth-specific parameters in the header or url, not the post body. For now this is the best way to keep the file data separate from the url encoded parameters.

 

Post a Reply

Post a reply to a note.

    • url: http://api.pownce.com/2.0/send/reply.{format}
    • request methods: POST
    • authentication: HTTP basic, OAuth
    • required url parameters:
  • {format} The expected response format. Options are xml, or json.
  • {app_key} The application key assigned during registration. Not required for OAuth.
    • required POST parameters:
  • {reply_to} The id of the note which this reply belongs to.
    • optional POST parameters:
  • {note_body} The main text body of the note.
  • {stars} (messages, links, and files) The star rating the user gave the original note. Options are 1, 2, 3, 4, or 5.
  • {rsvp} (events) The rsvp reply for an event type note. Options are 1 Attending, 2 Busy Already, 3 Not Attending, 4 Running Late, 5 Bringing Friends, 6 Undecided, or 7 Wishing I Could Come!
    • notes:
  • Returns the note that was posted in the requested response format with replies.
  • If no stars or rsvp POST parameter is present, then the note_body is required.

 

API 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.

 

The WWW-Authenticate header is returned for any endpoints which require authentication.

 

Pownce Integration

 

Send To Pownce

Post content to Pownce via a the Pownce website with a simple link.

 

    • default simple url: http://pownce.com/send/

 

Send a Message

    • url: http://pownce.com/send/message/
    • optional url parameters:
  • {note_body} The main text body of the note.
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
    • example link: http://pownce.com/send/message/?note_body=Hello+world%21¬e_to=public

 

Send a Link

    • url: http://pownce.com/send/link/
    • optional url parameters:
  • {url} The full url for the link.
  • {note_body} The main text body of the note.
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
    • example link: http://pownce.com/send/link/?url=http%3A%2F%2Fxkcd.com%2F388%2F¬e_body=Lemons+are+not+untasty%21

 

Send an Event

    • url: http://pownce.com/send/event/
    • optional url parameters:
  • {event_name} Name of the event.
  • {event_location} Location of the event.
  • {event_date} Date of the event in the format YYYY-MM-DD. Ex: 2008-01-16
  • {event_time} Time of the event in the format hh:mm. Ex: 20:00
  • {note_body} The main text body of the note.
  • {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
    • example link: http://pownce.com/send/event/?event_name=Drinking%20at%20Fly%20Bar&event_location=62%20Divisadero%20St,%20San%20Francisco,%20CA&event_date=2008-03-27&event_time=10:00¬e_body=Let's%20celebrate%20something.

 

Feeds

Note Feed

Atom feeds are currently available for all recent public notes as well as a user's public notes.

 

    • recent public notes: http://pownce.com/feeds/public/
    • user's notes: http://pownce.com/feeds/public/{username}/

 

Calendar Feed

There's an iCal feed for upcoming, attending, and all public events. This feed can be used with calendar applications such as Google calendar.

 

    • public events: webcal://pownce.com/ical/events/public/
    • my upcoming events: webcal://pownce.com/ical/events/upcoming/{syndication_key}/
    • events I'm attending: **webcal://pownce.com/ical/events/attending/{syndication_key}/