OAuth and API Providers: Come on guys...
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!
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)