Welcome to the BountyPix Developers Network. Here you can get information about the API built around BountyPix. We hope to give you all the tools that a developer would need to create any 3rd party application linked into BountyPix. As your probably aware of BountyPix API is a new venture and such the API is rapidly changing, please be patient with us and check back often for API updates, modifications, and additions to it. Please send any suggestions or information about bugs about the API to us, we greatly appreciate it! In this article we hope to show you how to connect to the BountyPix web services via our API.
Getting Started
Let's go over what you'll have to do to access BountyPix:
Understanding OAuth
BountyPix uses the OAuth standard to authenticate users. What is OAuth? Well if you really need the gory details, you can get those here, in short OAuth is a standard way of securely logging users into their accounts. Think of it this way, HTTP authentication is like an application asking for a key to your home, then going to your house and opening it up for you. Although it's secure, you still need to give out your house keys, your assuming the 3rd party app won't do anything malicious with them, and you have no idea if the path they took is secure. Now think of OAuth as an application taking you to your home and having you unlock it. You always have the keys in the hand, the app is simply transporting you to your home, you have no worries about malicious intent, or the path you took.
Thinking of this concept in terms of websites. When using OAuth you will send your users to our site, have them login normally, then BountyPix will redirect the user to a predefined URL (back to your site/app). Once redirected you will then use a secret key, passed back to you, in order to access the user's account. BountyPix tokens are read-write and can be used to access the account multiple times. So your ready to write your app, what do you do about non-web access?
There are plenty of OAuth examples and libraries on the web that will allow you to create a non-web application. Typically in those applications you will send the customer to our site and then direct them to go back to your application. These types of apps are out of the scope of this article, in this article we will cover a 3rd party web apps accessing BountyPix web services.
RESTful Communication
Another piece to the puzzle to the BountyPix API. REST works on the CRUD principals, Create Read Update Delete, it's basically a way to save URL real estate by using http methods to determine if the site should. Instead of going on and on about how great REST is, check out the wiki.
So why are we talking about this? You guessed it, BountyPix uses RESTful paths in the API. The details of the API are covered later in the article, just know we use REST and to get an understanding of it if you wish to use our API. Below in our API section, the posting methods are highlighted with brackets [ ] .
JSON, I think I love you!
JSON is a javascript communication layer. In the simplest form we're basically passing a string across the web server <-> 3rd party application. The string can then be converted into objects, depending on what language your using. Javascript is the underlying technology, that makes JSON possible. In the past (and still today) XML is the means by which most 3rd party API's communicate, but that seems to have changed recently. For more detailed information on JSON please check here, the main json site also has links to JSON libraries that deal with your client language of choice.
Currently, BountyPix ONLY supports JSON. There are plans to support XML in the future, but unless we get a surge of requests to change, we'll stick with JSON. If your a developer that would rather work with XML, please let us know, we would love to hear about you!
BountyPix Rails Client Example
Coming soon...
BountyPix uses JSON as the primary communication between 3rd party apps, we also use REST. There are plans in the works to support XML, but at the time of this writing JSON is the only communication process used. Below is a set of tables explaining the details of our API. Please be aware that BountyPix is currently in beta and should be treated as such. If you find any issues or have suggestions, please let us know! Any feedback is good feedback so don't be shy. All the items below can be found in the client example above. If you feel a particular API call needs more explanation or is not documented please tell us.
Response Codes
Your application should be able to handle these errors correctly.
Bounties
A bounty request will get you information on a particular bounty or the bounties the user has entered in, information you can gather is the same information displayed for each individual bounty. There are flags associated with the API that will allow your application to get more information than just the Bounty info. For example you could generate a request that returns a bounty along with photo URL's/info. Please be aware requesting more information than just the bounty will cause the request to take longer.
Request : [GET] /bounties.json
| Fields | |
| search | |
| paginate | optional, integer (default : 20), when returning bounties only the latest 20 bounties will be returned. To return all bounties set this value to -1. |
| page | optional, integer (default : 1), if bounties are paginated page determines which page to return |
| start_date | optional, date (default : Date.1.year.ago), look for bounties that have been started at this value. |
| end_date | optional, date (default : Date.today), look for bounties that have ended by this value. |
| opened | optional, boolean (default : true). If set to false the request will return expired bounties, if set to true it will return ongoing bounties. |
Request : [GET] /bounties/show/{BountyID}
| Fields | |
| photos | optional, boolean (default : false), include all photos |
| votes | optional, boolean (default : false), include voting information, must be used with photos set to true. |
| paginate_photos | optional, integer (default : 20), when returning photos only the latest 20 photos will be returned. To return all photos set this value to -1. |
Photos
Photo requests allow you to get information such as the number of votes it has, who uploaded the photo, when it was submitted etc... Photos are always linked to particular bounties, as such you must pass the bountyID along with the photo information, photoID.
Request : [GET] /bounties/{bountyID}/photos.json
| Fields | |
| votes | optional, boolean (default : true), include voting information with photos |
| search | optional, string (default : ''), string to search photos with. Comments of the photos will be searched. |
| paginate | optional, integer (default : 20), when returning photos only the latest 20 photos will be returned. To return all photos set this value to -1. |
| page | optional, integer (default : 1), if photos are paginated page determines which page to return. |
| start_date | optional, date (default : Bounty.start_time), look for photos that have been uploaded starting at this value. |
| end_date | optional, date (default : Date.today), look for photos that have been uploaded ending at this value. |
Voting
The voting API allows users to submit votes and flag photos for inappropriate content. Votes are not only linked to photos but also to bounties, as such when generating requests the application must pass the bountyID as well as the photoID, along with the vote.
Request : [GET] /bounties/{bountyID}/photos/{photoID}/vote.json
| Fields | |
| yes_vote | optional, boolean (default : false), Voting with a thumbs up for this particular photo |
Accounts
Every user has a unique account. The account stores information such as paypal e-mail address, the amount of money in their Bounty Account, and settings. Because the API is a read-write API you will have the ability to modify users account information, if needed.
// TBD
Direct comments or concerns to : customerservice@bountypix.com
