@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.
4 Responses
Stephen,
Woo! Feedback!
The problem with all things being in the same namespace (everything just keys in one kvp) is expansion. In practice, clients all re-invent the same concept, and now I want to bake in support. I can either choose a funky name, prefix the name and make it ugly, or there’s a large chance of conflict. Even with those measures, there’s a decent chance unless I pre-publish the prefix I am going to use, which means that all keys are ugly. Ah, in later section I see that you used xml-namespaces to avoid this issue. Going with something standard like XML namespaces make the prefix less ugly, I’ll admit.
Threshold wasn’t that bad. It’s actually already implemented in my minimal non-reviewed code that was used to iron out spec details. I will admit that increment/decrement were the commands with the most code behind them.
Basing IDs off of the HTML ID spec is a good idea! I’m definitely using that one with no backtalk!
While I didn’t say it explicitly, I meant to imply that the KVPs were created with the meta site. It’s part of award creation, and all award creation is (currently) done on the site.
Hoookay, OAuth. I expected some push back. I’ll explain my thinking.
My biggest current problem with OAuth is in how I want to handle user accounts. An authentication scheme that revolves around attaining user permission is something I want to avoid as an attempt at being mostly white-label. From your comments, I need to either explain my goals regarding user accounts better or re-think it completely. And I didn’t COMPLETELY reinvent OAuth. There are no nonces, and no reliance upon provider user accounts, or required user interaction with the provider. Especially the provider-user interaction are important to me.
MD5 was chosen for a couple of reasons. Firstly, I know that it’s available built-in (or for the more modular, in the base library) to any language I care about. Choosing something and publishing it causes comments like this! Having seen what happens when you try to use bigints in PHP, what one-way hash would you suggest? I’d LIKE it to be in the default library of every major programming language. OAuth is, in my opinion, nearly incomprehensible. I’m trying to stay fairly easy to implement.
The image display size restrictions are mostly for an eventual meta site. The users who have logins would be able to display all of their awards on their profile pages. A consistent display size is important to publish. I was leaning toward not trying to actually restrict it (I really don’t want to load some image library and parse the image just to approve it), but to publish what the eventual display size on the meta site would be so that they wouldn’t have to be resized if the API users followed my guidelines.
140 characters: Agreed, but what can be done about it? There will eventually be an API to allow users to pull in their own recent achievements, and each site is probably going to have a leaderboard, etc. I don’t control any of these sites. I expect most will want to put the summary on a single line. Publishing a limit allows the smarter people to adjust their design so that it probably could show up on one line, and those that don’t read spec either don’t care if it wraps, or will fix when they come across one in the real world. I’m actually leaning toward a lower limit, but this sort of thing is hard to do before I see how people really use it.
Yes, I almost put in a section on unicode/etc in this latest rev of the spec, but decided against it as I was tired and would probably make huge mistakes. I’m leaning toward restricting to English-centric ASCII in the old school manner, largely because every bit of documentation I’ve ever found on anything unicode leaves me more confused than ever. Values were changed from binary blobs to textual from v1 to v2 because I really could not think of a valid use for binary data in the intermediate time (almost all of which was used implementing and revising spec).
The use case of users/create is… it feels wrong to not at least offer it? Maybe I don’t, in fact, need it.
I will take a good look at the spec for ATOM and look at Salmon and Ostatus as well. Good pointers!
I appreciate the feedback. I’ve never done big-design API before, which is why I’m doing so publicly, to get feedback like this. If this existed today, are there any concerns not in this initial post that would prevent you from using it for whatever you had in mind when you wrote your initial post?
Having looked at ATOM, there are many required elements that do not apply to me. I could bastardize the spec… but I think I’ll take some good ideas and not claim compatibility since I’m leaving out things like permanent URLs for individual items.
I don’t thin it’s as many as you might think (1 or 2?), but even if it is, I will say to you what I say to everyone trying to invent something new: reuse is good! People have a tendency to say “well, this existing tech has something required that I don’t need/want, so I’ll invent a whole new thing.” Wrong! Reusing the existing vocabulary (and, in the case of XML, namespace) means that existing parsers can make some sense of your content without needing to know you exist. It also means that devs familiar with that vocabulary understand more of your content more easily. In fact, if everyone uses almost the same vocabulary for the same kind of data everywhere, this works out even better.
You may prefer <guid> to <id> or “creator” to author or activity-actor, or url to link, but honestly where does inventing a new vocabulary get you?
The biggest thing here, also, is re-syndication. If you hand me a bunch of ATOM-based blobs, I can send them on to someone else as a feed or over PuSH trivially, and then they can process as much of the data as they understand, which thanks to the common vocabulary may be quite a lot of it.
Marketing tends to fail a lot. It confuses too many people. This may be what OAuth is often used for but it is not what OAuth is. OAuth is a generic protocol for signing arbitrary HTTP requests using any signing method that uses two pieces of data for signing (or, realistically, one, and leave the other as a blank string). So, you issue your clients two tokens (I prefer two for durability. If you need, for security reasons, to upgrade your signing method in the future, more of them need 2 than can work with 1) and they use them as the access token/secret. If you look at the spec, though, you’ll see that what you call the two tokens is mostly a library thing. Really, in all cases, you just order the parameters a certain way, include other important information (like the verb) and the sign with the chosen signing mechanism. I would suggest HMAC-SHA1 for now, as it’s still basically secure (SHA1 attacks aren’t practical yet) and it is very well supported (both by languages, and by the libraries that exist for basically all your favourite languages, including C liboauth). Nonces are actually optional, though recommended.
OAuth is both not hard to implement (I’ve done it twice) and you don’t need to implement it because there are libraries already.
What are you reading that makes it complicated. I implemented UTF-8 in a CS course. If the idiots in CS courses can be expected to do it, it can’t be that hard. Perhaps you are reading something evil?
Do not count out all of everyone who is not English. Seriously. Half the time you won’t even need to parse the stuff, just store it and pass it through blindly. If you make limits in bytes instead of chars, this solves your counting problem.
UTF-8 is the only charset anyone should be using for anything (except internal representation, which is handled for you in scripting languages usually). Benefit is you can pretend it’s ASCII in the english case, and if you treat it like ASCII you’ll be fine unless you’re truncating or length-measuring.
Oh… that’s a bit odd. Why not just let me POST the award I want when awarding it and then store that? Works magically better for everything except threshold.
Hmm, I see. We do have two slightly different goals here, but I don’t think said goals have to be incompatible. You want a white-label “I will store your awards for you” API, and I want an awards syndication/sharing/republication system. I basically assume that my app can handle awards existing by itself (especially in the offline case), but I want a way to share/publish the awards.
This is part of why I want awards to be POSTable instead of pre-created. That way an app can hook up to anything supporting this API and just go.
Basically, though, the API ends up looking the same. If an app wants white-label, they sign up for a white-label keypair and use that to auth. If they want to publish for their user, they get tokens for that user’s account and publish with that auth. You don’t have to support both in your implementation, but I’d like both to be supported in the spec (at least conceptually).
Speaking of spec and interop, at some point we should talk discovery. Unless you don’t care about the non-white-label case at all, in which case i can fork your spec later and add discovery for my use case 🙂
Note to any readers:
Daniel Grace has also blogged about this at http://www.argtechnologist.com/blog/16/