the documentation lied: publish_stream vs. publish_actions

It may surprise you to discover I still work with Facebook on a daily basis. I did leave Facebook as a user over three years ago, but wrangling the Graph API is still a core part of my job. (For the web developers among you: It’s like your relationship with Internet Explorer.)

Last week I was updating Measured Voice to match changes in the Facebook permissions dialog, and I noticed that the documentation said one of my permissions was now out of date:

“Facebook used to have a permission called publish_streampublish_actions replaces it.”

– from the Facebook API’s Extended Permissions documentation

In a fit of eagerness, I broke the first rule of API usage* and switched out publish_stream for publish_actions. However, it soon became obvious that the two weren’t equal. The auth tokens produced before and after my update were markedly different:

with publish_stream

Requested Granted
manage_pages manage_pages
read_insights read_insights
user_about_me user_about_me
user_status user_status
publish_stream publish_stream
publish_actions
video_upload
create_note
photo_upload
share_item
status_update

with publish_actions

Requested Granted
manage_pages manage_pages
read_insights read_insights
user_about_me user_about_me
user_status user_status
publish_actions publish_actions

Requesting publish_stream gave me publish_actions anyway, which makes sense if the two are being treated as equals, but it also gave me a whole passel of other permissions I hadn’t asked for. As it turns out, at least one of those permissions is still necessary to do what I need: post status updates and photos to a Facebook Page.

But which one? I checked the documentation again, and… well, none of them are documented at all. Not listed anywhere, not mentioned as deprecated, not anything. Huh. Some of them do sound like permissions I’d need (photo_upload and status_update, for example), but without documentation it’s just a guess.

It sounds like the documentation is ahead of the actual API development, and reflects some design goal instead. Or maybe this is (yet another) API bug. Either way, I’m going back to requesting publish_stream until they get their facts straight. It still works. (For now.)

* “If it ain’t broke, don’t upgrade to the new revision.”