@codenamebowser has written up a minimal Awards API spec similar in nature to what I proposed recently. @wolever has already made some comments. My comments are below.

OAuth: yes. Be aware that OAuth (and really any other system) cannot securely identify non-web apps. This is because auth keys stored in an app in the possesion of a user can be got by that user. Many people (including myself and the IETF OAuth spec editor, Eran Hammer-Lahav) feel that desktop/mobile apps should not use consumer tokens at all, but should use empty or “anonymous” tokens so the app can say to the user “an application claiming to be…”

User Accounts: whaaa? I guess you’re trying to let sites use the system if their users don’t, but you really probably want to be publishing to an actual usr account, not an invented thing. Make a way for new users to seamlessly get an account. You could start OAuth from the client and when they come if they have an account, log them in and associate. Otherwise get some ID from them (email address or web address) and use that to authenticate them (using email verification and/or openid and/or relmeauth).

I agree with @wolever that if you’re going to have limits, you should make them early on. Most things shouldn’t need limits, though.

I would make sure all properties are accessed as though they are just keys in the allswed kvp. That way the whole API is simpler and feels the same as itself. Some keys are just predefined with meaning and some aren’t.

Threshold seems like overkill for v1. The client probably knows that anyway.

If you want likits for IDs, look up the limits on the HTML ID attribute.

As @wolever says, don’t count on one user = one email.

This draft doesn’t say how the kvps are going up to the server. form encoded post? While a bit more complex, I would look into POSTing activity streams ATOM, since that will allow distributedness and resyndication to work very well.

Before I got to publishing this a new version of the API spec came out. More comments below.

Authentication: what? I’m reading this, and you have exactly re-invented OAuth. As always when re-inventing a security technology, you have done it poorly (md5? are you on crack?) Use OAuth… it’s the same basic tech you’re suggesting, but is actually good.

Must have for icon is PNG. I think size restrictions would be bad at an API level, though for your implementation you may want to institude a MB limit to prevent abuse.

140 characters is a nice arbitrary limit for SMS, but saying it makes things fit on one line in web designs is just not fair.

In the KvP, are values 8-bit safe? Can I use a 255-byte blob? 8-bit safety is *good*. Make your limits in bytes, not in characters.

users/create_and_retrieve seems like the only one that’s really useful (except maybe retrieve). What’s the use case for users/create? Of course, as above, I think it would be useful to handle user accounts somewhat differently.

Your XML seems like a good candidate for ATOM, as I suggested:

<entry>
	<author><email>dgrace@doomstick.com</email></author> <!-- this could be activity-actor as well/instead -->
	<id>test</id>
	<award:points>10</award:points>
	<title>Test achievement</title>
	<content>Got this for being a guinnea pig.</content> <!-- could use summary for this instead -->
	<link rel="logo" type="image/png" href="data:..." />
	<award:testkey>testvalue</award:testkey>
</entry>

This format (or something similar) has resyndication benefits, and also means that one could pass awards around easily using Salmon or Ostatus.

I’ve been thinking a bit recently about generic achievement systems. Basically what I want, is a web service where I’ve got a profile showing off the achievements I’ve unlocked in different ways. This could have some scraping of well-known social web achievements (StackOverflow, FourSquare), but that doesn’t really scale so I’d want an API that any service or application could tie into to publish unlocked achievements to my profile. I’d also want read APIs so I can put achievements I really want to show off on my actual profile page at singpolyma.net. Achievements should be able to take any image+text form, from high scores to badges.

If social web sites can publish achievements to the site and read them back out, that’s great, but there are already a couple of services that sort of serve that purpose (though I’m not sure either serves their own local profile pages). The real benefit here is that applications (especially including games) could easily tie into this as well.

Of course, now that I’ve described it you can see I don’t necessarily want a web service at all. I want an API specification and a reference implementation. Web apps and games should be configurable with my actual “achievement host” (or discover it over LRDD/Webfinger) so that I can just host my own list and not sharecrop on someone else.

Now, on top of all this, I want the same protocol (or something very close to it) to work with a local on-my-machine service that serves a similar purpose: storing scores and achievements for local users. One could then build nice local scoreboard/achievements unlocked display dashboards, which could be very useful in a gaming-heavy environment like the games at www.lionwins.com (some games already do shared local highscores, this is just one up on that).

The right way to build something like this, probably, is to use Activity Streams concepts and publish the content over HTTP as an “achieved” or “scored” event.