Award API

badges.mozilla.org is alpha testing a simple award issuing API. Until I get around to better documentation, here's how you use it:

1. Login, visit your profile, click the Manage valet keys button.

2. Create a new valet key, jot down the user name & password somewhere private & safe like a local note pad or config file. For example, I created a shell file like so:

    % cat > play-keys-prod.sh
    KEY_USER=khCN2gibWrLcPH2Qay8RfpQ1vETL6SibaqqZwFgqKGA
    KEY_PASS=u2JSnId2n3BotOGGa6tJC1hcirSMSpPgJvqDPz5LZHE
    ^D
    % . ./play-keys-prod.txt
   

   DO NOT CHECK THESE INTO GITHUB.

3. Create or find a badge for which you have permission to issue awards. Note the URL of the detail page.

   eg. https://badges.mozilla.org/en-US/badges/badge/the-les-orchard-seal-of-approval

4. Visit the awards page for that badge, or just add /awards to the end of the badge URL. This is the URL for the award issuing POST API for that badge. Save this somewhere in your script:

    % URL='https://badges.mozilla.org/en-US/badges/badge/the-les-orchard-seal-of-approval/awards'
   

5. Assemble a list of email addresses and an explanation for awarding the badge to those people. Express it in JSON like so:

    % cat > payload.json
    {
        "description": "These are hoopy froods",
        "emails": [
          "me@lmorchard.com",
          "lorchard@mozilla.org",
          "l.m.orchard@pobox.com"
        ]
    }
    ^D
   

   The description field is optional, but emails is required.

6. POST this as a request body with Content-Type: application/json to the awards URL, using the username and password from the valet key:

    % curl -si -u$KEY_USER:$KEY_PASS -X POST -H'Content-Type: application/json' -d @payload.json $URL
    HTTP/1.1 200 OK
    Content-Type: application/json
    Date: Mon, 04 Mar 2013 22:24:11 GMT
    Content-Length: 136
   
    {"successes": {"lorchard@mozilla.org": "INVITED", 
                   "l.m.orchard@pobox.com": "INVITED"},
     "errors": {"me@lmorchard.com": "ALREADYAWARDED"}}
   

7. Some common error conditions:

   • 403 Forbidden, if you've used the wrong user/pass.
   • 403 Forbidden, if you try to award a badge for which you haven't go permission.
   • 400 Bad Request, if your request body is invalid JSON or is missing the emails field. The response bodies for these will be text/plain and should offer some English description of the issue.

8. On a successful POST, you should receive a 200 OK response with an application/json body.

   • The resulting object should have two root keys: successes and errors.
   • successes will offer a mapping of email address with a description of a successful award
     • AWARDED for an email associated with an existing account
     • INVITED for an email that has not yet been used to sign into the site
   • errors will offer a mapping of email addresses for which awarding failed:

     • ALREADYAWARDED for an email to which a unique badge has already been awarded

     • EXCEPTION {msg} as a catch-all for anything else that might go wrong during the process

       There is not yet an API for querying whether a given email address has already been awarded a badge. So, It's best to create the badge as "unique" and either track previous awards locally or just go ahead and attempt duplicate awards and accept the ALREADYAWARDED error.