Technorati Tags:
FacebookJust recently, I complained a bit to Facebook about this page of their API: http://wiki.developers.facebook.com/index.php/Photos.get
Why? Because it was not clear to me how to pass the UserID to the HttpWebRequest in order to query all photos by that UserID.
For example, if you took a look at the description of parameters for the photos.Get method call (before they changed it), you saw the following:
Parameters
| Required | Name | Type | Description |
| required | api_key | string | The application key associated with the calling application. | |
| | session_key | string | The session key of the logged in user. | |
| | call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. | |
| | sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. | |
| | v | string | This must be set to 1.0 to use this version of the API. | |
| | subj_id | int | Filter by photos tagged with this user. You must specify at least one of subj_id, aid or pids. The subj_id parameter has no default value, but if you pass one, it must be the user's user ID. | |
| | aid | string | Filter by photos in this album. You must specify at least one of subj_id, aid or pids. The aid parameter has no default value. The aid cannot be longer than 50 characters. | |
| | pids | array | Filter by photos in this list. This is a comma-separated list of pids. You must specify at least one of subj_id, aid or pids. The pids parameter has no default value. | |
| optional | format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | |
| | callback | string | Name of a function to call. This is primarily to enable cross-domain javascript requests using the <script> tag, sometimes known as "JSONP". This works with both XML and JSON. | |
Now where would I pass the uid I thought? I am not using FQL at the moment (just API calls instead to do the same) so I did not really care to scroll down further because I knew all their pages dive into FQL at that point mostly. I scrolled only enough to get to the FQL and back up. But eventually I decided to hunt further since I saw no way of passing a uid to the request, and found the following FQL:
SELECT pid, aid, owner, src, src_big, src_small, link, caption, created
FROM photo WHERE pid IN (SELECT pid FROM photo_tag WHERE subject=<uid>)
AND aid=<aid> AND pid IN (pid)
Notice the subject=<uid>
I scrolled back up and thought ok, must be the equivalent to the method param called subj_id because it stated “this user” in its description which I equate to uid in my head.
If I had not taken a look at the FQL below it, and had Facebook not included that particular field check in the FQL example (which knowing their docs is completely possible) I’d be screwed. I would have had no idea how or if the uid could be passed.
So luckily after I brought this to their attention, they changed it to:
|
“subj_id int
Filter by photos tagged with this user. You must specify at least one of subj_id, aid or pids. The subj_id parameter has no default value, but if you pass one, it must be the user's user ID.”
|
Some developers can document, and some just cannot or it’s that they do not make an effort or care how it comes across. The sentence is such a run-on and just is weird wording. it leaves me with these questions:
> Why is there no uid when most of the methods in the Facebook API take a uid?
> What does sub_id have to do with uid? Weird. I found out later that uid is appended to sub_id after reviewing my Facebook account.
The way I would have worded it was (I added in green):
|
“subj_id int
Filter by photos tagged with this user. You must specify at least one of subj_id, aid or pids. The subj_id parameter has no default value.
Note: While most Facebook API method calls take a uid, we use subj_id as the means to query photos based on a specific userID.
You will receive back only those photos found in that user’s “Photos of <uid’s name>” section of Facebook.
Using this parameter will not retrieve all photos across all albums. For this, you must pass all Album aids into a request to photos.get instead.
|
Now you’re thinking wow man, that’s a lot of text dude. Sure…to some it may be, but it’s not really that much honestly. But it clearly explains to you what’s going on with that parameter since it DOES relate to uid…who would ever know. And if it’s a lot, then hey, shove the remainder into an expandable JQuery control then and hide it. But surely show detailed information like this.
This I figured out pretty quickly on my own to be honest (within a few minutes) just from pure observation of everything on their page, but in most circumstances you spend hours trying to figure out how to use the Facebook API. And some developers may not put that puzzle together as quickly as you or I did so details are useful.
I’ve gotten my implementation of Facebook working for a current project I’m working on. But it sure could have been much less painful if Facebook would have decent documentation and sentences that make sense, don’t stop in the middle, and give more explanation to the process of calls, POSTs, and much more.
I encourage you to complain to Facebook if their current documentation is not adequate. They seem to be open to improving so provide them with the link and how it can be improved. There are many pages you just cannot edit in the wiki. As one who likes to help the community, I was tempted to edit it many times.
With that, I hope to contribute more here on my blog providing better explanations or tips in the near future as it pertains to Facebook in general and Facebook with .NET.
