@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>firstname.lastname@example.org</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.