summaryrefslogtreecommitdiffstats
path: root/Godeps/_workspace/src/github.com/huandu
diff options
context:
space:
mode:
Diffstat (limited to 'Godeps/_workspace/src/github.com/huandu')
-rw-r--r--Godeps/_workspace/src/github.com/huandu/facebook/README.md347
1 files changed, 347 insertions, 0 deletions
diff --git a/Godeps/_workspace/src/github.com/huandu/facebook/README.md b/Godeps/_workspace/src/github.com/huandu/facebook/README.md
new file mode 100644
index 000000000..a21de8d7c
--- /dev/null
+++ b/Godeps/_workspace/src/github.com/huandu/facebook/README.md
@@ -0,0 +1,347 @@
+# A Facebook Graph API SDK In Golang #
+
+[![Build Status](https://travis-ci.org/huandu/facebook.png?branch=master)](https://travis-ci.org/huandu/facebook)
+
+This is a Go package fully supports Facebook Graph API with file upload, batch request, FQL and multi-FQL. It can be used in Google App Engine.
+
+API documents can be found on [godoc](http://godoc.org/github.com/huandu/facebook).
+
+Feel free to create an issue or send me a pull request if you have any "how-to" question or bug or suggestion when using this package. I'll try my best to reply it.
+
+## Get It ##
+
+Use `go get -u github.com/huandu/facebook` to get or update it.
+
+## Usage ##
+
+### Quick start ###
+
+Here is a sample to read my Facebook username by uid.
+
+```go
+package main
+
+import (
+ "fmt"
+ fb "github.com/huandu/facebook"
+)
+
+func main() {
+ res, _ := fb.Get("/538744468", fb.Params{
+ "fields": "username",
+ "access_token": "a-valid-access-token",
+ })
+ fmt.Println("here is my facebook username:", res["username"])
+}
+```
+
+Type of `res` is `fb.Result` (a.k.a. `map[string]interface{}`).
+This type has several useful methods to decode `res` to any Go type safely.
+
+```go
+// Decode "username" to a Go string.
+var username string
+res.DecodeField("username", &username)
+fmt.Println("alternative way to get username:", username)
+
+// It's also possible to decode the whole result into a predefined struct.
+type User struct {
+ Username string
+}
+
+var user User
+res.Decode(&user)
+fmt.Println("print username in struct:", user.Username)
+```
+
+### Read a graph `user` object with a valid access token ###
+
+```go
+res, err := fb.Get("/me/feed", fb.Params{
+ "access_token": "a-valid-access-token",
+})
+
+if err != nil {
+ // err can be an facebook API error.
+ // if so, the Error struct contains error details.
+ if e, ok := err.(*Error); ok {
+ fmt.Logf("facebook error. [message:%v] [type:%v] [code:%v] [subcode:%v]",
+ e.Message, e.Type, e.Code, e.ErrorSubcode)
+ return
+ }
+
+ return
+}
+
+// read my last feed.
+fmt.Println("my latest feed story is:", res.Get("data.0.story"))
+```
+
+### Read a graph `search` for page and decode slice of maps
+
+```go
+res, _ := fb.Get("/search", fb.Params{
+ "access_token": "a-valid-access-token",
+ "type": "page",
+ "q": "nightlife,singapore",
+ })
+
+var items []fb.Result
+
+err := res.DecodeField("data", &items)
+
+if err != nil {
+ fmt.Logf("An error has happened %v", err)
+ return
+}
+
+for _, item := range items {
+ fmt.Println(item["id"])
+}
+```
+
+### Use `App` and `Session` ###
+
+It's recommended to use `App` and `Session` in a production app. They provide more controls over all API calls. They can also make code clear and concise.
+
+```go
+// create a global App var to hold app id and secret.
+var globalApp = fb.New("your-app-id", "your-app-secret")
+
+// facebook asks for a valid redirect uri when parsing signed request.
+// it's a new enforced policy starting in late 2013.
+globalApp.RedirectUri = "http://your.site/canvas/url/"
+
+// here comes a client with a facebook signed request string in query string.
+// creates a new session with signed request.
+session, _ := globalApp.SessionFromSignedRequest(signedRequest)
+
+// if there is another way to get decoded access token,
+// creates a session directly with the token.
+session := globalApp.Session(token)
+
+// validate access token. err is nil if token is valid.
+err := session.Validate()
+
+// use session to send api request with access token.
+res, _ := session.Get("/me/feed", nil)
+```
+
+### Use `paging` field in response. ###
+
+Some Graph API responses use a special JSON structure to provide paging information. Use `Result.Paging()` to walk through all data in such results.
+
+```go
+res, _ := session.Get("/me/home", nil)
+
+// create a paging structure.
+paging, _ := res.Paging(session)
+
+// get current results.
+results := paging.Data()
+
+// get next page.
+noMore, err := paging.Next()
+results = paging.Data()
+```
+
+### Read graph api response and decode result into a struct ###
+
+As facebook Graph API always uses lower case words as keys in API response.
+This package can convert go's camel-case-style struct field name to facebook's underscore-style API key name.
+
+For instance, to decode following JSON response...
+
+```json
+{
+ "foo_bar": "player"
+}
+```
+
+One can use following struct.
+
+```go
+type Data struct {
+ FooBar string // "FooBar" maps to "foo_bar" in JSON automatically in this case.
+}
+```
+
+Decoding behavior can be changed per field through field tag -- just like what `encoding/json` does.
+
+Following is a sample shows all possible field tags.
+
+```go
+// define a facebook feed object.
+type FacebookFeed struct {
+ Id string `facebook:",required"` // this field must exist in response.
+ // mind the "," before "required".
+ Story string
+ FeedFrom *FacebookFeedFrom `facebook:"from"` // use customized field name "from"
+ CreatedTime string `facebook:"created_time,required"` // both customized field name and "required" flag.
+}
+
+type FacebookFeedFrom struct {
+ Name, Id string
+}
+
+// create a feed object direct from graph api result.
+var feed FacebookFeed
+res, _ := session.Get("/me/feed", nil)
+res.DecodeField("data.0", &feed) // read latest feed
+```
+
+### Send a batch request ###
+
+```go
+params1 := Params{
+ "method": fb.GET,
+ "relative_url": "me",
+}
+params2 := Params{
+ "method": fb.GET,
+ "relative_url": uint64(100002828925788),
+}
+results, err := fb.BatchApi(your_access_token, params1, params2)
+
+if err != nil {
+ // check error...
+ return
+}
+
+// batchResult1 and batchResult2 are response for params1 and params2.
+batchResult1, _ := results[0].Batch()
+batchResult2, _ := results[1].Batch()
+
+// Use parsed result.
+var id string
+res := batchResult1.Result
+res.DecodeField("id", &id)
+
+// Use response header.
+contentType := batchResult1.Header.Get("Content-Type")
+```
+
+### Send FQL query ###
+
+```go
+results, _ := fb.FQL("SELECT username FROM page WHERE page_id = 20531316728")
+fmt.Println(results[0]["username"]) // print "facebook"
+
+// most FQL query requires access token. create session to hold access token.
+session := &fb.Session{}
+session.SetAccessToken("A-VALID-ACCESS-TOKEN")
+results, _ := session.FQL("SELECT username FROM page WHERE page_id = 20531316728")
+fmt.Println(results[0]["username"]) // print "facebook"
+```
+
+### Make multi-FQL ###
+
+```go
+res, _ := fb.MultiFQL(Params{
+ "query1": "SELECT username FROM page WHERE page_id = 20531316728",
+ "query2": "SELECT uid FROM user WHERE uid = 538744468",
+})
+var query1, query2 []Result
+
+// get response for query1 and query2.
+res.DecodeField("query1", &query1)
+res.DecodeField("query2", &query2)
+
+// most FQL query requires access token. create session to hold access token.
+session := &fb.Session{}
+session.SetAccessToken("A-VALID-ACCESS-TOKEN")
+res, _ := session.MultiFQL(Params{
+ "query1": "...",
+ "query2": "...",
+})
+
+// same as the sample without access token...
+```
+
+### Use it in Google App Engine ###
+
+Google App Engine provide `appengine/urlfetch` package as standard http client package. Default client in `net/http` doesn't work. One must explicitly set http client in `Session` to make it work.
+
+```go
+import (
+ "appengine"
+ "appengine/urlfetch"
+)
+
+// suppose it's the appengine context initialized somewhere.
+var context appengine.Context
+
+// default Session object uses http.DefaultClient which is not allowed to use
+// in appengine. one has to create a Session and assign it a special client.
+seesion := globalApp.Session("a-access-token")
+session.HttpClient = urlfetch.Client(context)
+
+// now, session uses appengine http client now.
+res, err := session.Get("/me", nil)
+```
+
+### Select Graph API version ###
+
+See [Platform Versioning](https://developers.facebook.com/docs/apps/versions) to understand facebook versioning strategy.
+
+```go
+// this package uses default version which is controlled by facebook app setting.
+// change following global variable to specific a global default version.
+fb.Version = "v2.0"
+
+// starting with graph api v2.0, it's not allowed to get user information without access token.
+fb.Api("huan.du", GET, nil)
+
+// it's possible to specify version per session.
+session := &fb.Session{}
+session.Version = "v2.0" // overwrite global default.
+```
+
+### Enable `appsecret_proof` ###
+
+Facebook can verify Graph API Calls with `appsecret_proof`. It's a feature to make Graph API call more secure. See [Securing Graph API Requests](https://developers.facebook.com/docs/graph-api/securing-requests) to know more about it.
+
+```go
+globalApp := fb.New("your-app-id", "your-app-secret")
+
+// enable "appsecret_proof" for all sessions created by this app.
+globalApp.EnableAppsecretProof = true
+
+// all calls in this session are secured.
+session := globalApp.Session("a-valid-access-token")
+session.Get("/me", nil)
+
+// it's also possible to enable/disable this feature per session.
+session.EnableAppsecretProof(false)
+```
+
+### Debugging API Requests ###
+
+Facebook introduces a way to debug graph API calls. See [Debugging API Requests](https://developers.facebook.com/docs/graph-api/using-graph-api/v2.3#debugging) for details.
+
+This package provides both package level and per session debug flag. Set `Debug` to a `DEBUG_*` constant to change debug mode globally; or use `Session#SetDebug` to change debug mode for one session.
+
+When debug mode is turned on, use `Result#DebugInfo` to get `DebugInfo` struct from result.
+
+```go
+fb.Debug = fb.DEBUG_ALL
+
+res, _ := fb.Get("/me", fb.Params{"access_token": "xxx"})
+debugInfo := res.DebugInfo()
+
+fmt.Println("http headers:", debugInfo.Header)
+fmt.Println("facebook api version:", debugInfo.FacebookApiVersion)
+```
+
+## Change Log ##
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## Out of Scope ##
+
+1. No OAuth integration. This package only provides APIs to parse/verify access token and code generated in OAuth 2.0 authentication process.
+2. No old RESTful API support. Such APIs are deprecated for years. Forget about them.
+
+## License ##
+
+This package is licensed under MIT license. See LICENSE for details.