The more OAuth providers there are, the more inconsistency there is. Not following the specification puts an increased and unnecessary burden on the developer.
In the past couple of weeks I have coordinated and authenticated with more than my fair share of OAuth providers. That being said, you should be thinking "Hey, isn't OAuth a specification?" Once you do one you should be simply swapping out keys and urls and you should be good to go right? So wrong.
Follow the specification and be consistent.
This article is meant to let the OAuth providers know some of the pain points of dealing with them as providers and steps they could take to make interacting with their API a joy.
Like with all documentation, I need to experience joy in the first 15 minutes otherwise your documentation has failed. Clearly outlining API endpoints and how I can get the data I need is crucial. Also another big win that some APIs provide (like Foursquare and Google) is an API explorer which shows you how to make a request and what to expect as a response. Amazing for getting familiarized with a new API.
Don't point me at another services documentation (looking at you Tumblr) write your own.
Another thing that enrages me to no end is the lack of consistency. If you are returning JSON formatted data in some places and returning the body of a HTML page in others you are doing it wrong. This requires me to do two things: process which ones return JSON and which return HTML data I have to parse. Pick a way to represent the information returned from your API and be consistent. But I believe the specification has something to say about this.
Error pages should also return data in a consistent manner.
Now a lot of OAuth providers don't provide appropriate graphics for using their services. I want to use your service to authenticate my users, but you aren't providing proper graphics for my site.
You would think that OAuth providers would want to have the most amazing logo being sent out to the public. Twitter does an excellent job of this, it has also increased Twitter's presence as an OAuth provider on tons of sites and applications. Do the graphics have something to do with it? Maybe!
Screencap of Twitter authentication buttons
Let's be honest we have all seen this. Make the effort provide logos, buttons and anything else I may need to properly identify your service in the authentication process.
Now when a user signs up websites try to make it as easiest as possible to increase user sign up and adoption. Then you provide an API that exposes this information and has data gaps because you wanted to avoid having the user type in one more field during sign up. The API should drive those requirements not the other way around.
Another important thing I find that some providers are ignoring (like Tumblr) is a unique id for your users. It is absolutely essential for each user to have UID that doesn't change and is consistent for the life of the account.
If you run a business and decide to become an OAUTH provider or support an API it is essential that you put as much emphasis on this portion of the product as you would on any other core feature. It portrays your attention to detail as well as your ability to build a cohesive product. This should translate to an eager development community working with your tools rather than writing snarky blog posts complaining about them. :)
- Follow the specification.
- Provide clear and concise documentation.
- Provide graphics.
- API should be consistent with the rest of the website/service.