API documentation is necessary

[Mithgol]

It seems that currently README.md does not explain the API, it merely provides some examples.

Sometimes these examples are enough, but the understanding of the API might still be deeper if the parameters of the constructors (.OAuth, .OAuth2) and methods (.get, .getOAuthAccessToken) were explicitly explained somewhere.

[thenitai]

+1

[jobsamuel]

I'd like to have an API explanation too.

[mgan59]

:+1: Yeah on first coming to this lib and not having worked with OAuth in several years it was abit bumpy to learn/piece everything together.

The provided github example was helpful once I realized how OAuth2.0 works from a spec, how each social network is different, and how it all fits within my application container. Specifically, In my case I needed to connect to Facebook so understanding how to use the getAuthorizeUrl vs getOAuthAccessToken in conjunction with my web-server handling redirects through a proxy layer took some research.

It is probably out of scope for a readme.me to document everything I had todo/research. But the readme should probably link to a OAuth-Primer of sorts which could use the github-example-code to illustrate some of the points. Might also help to have a facebook-example as well. Also, as in my case, I created a server-endpoint that acts as a proxy-layer which is how some other apps do it, I noticed the buffer-app does it this way. For this type of OAuthing you need to make a server-side request to the Authorize url which then handles the various 302 redirects and this type of example would also be helpful I think for others to conceptualize how everything fits together.

I'll see if I can submit some prs for documentation, I'm currently documenting some stuff on my end and it could be helpful here.

[krlng]

I am facing the same problem as @mgan59 : Authenticating against facebook thorugh proxy. Would be really interested in those documentation PRs of @mgan59 .

[mgan59]

@nik-ffm I never opened a PR with additional docs and I'm somewhat removed from this code now. I put this little snippet together it may help, but essentially I ended up handling the direct using another server-side request library that made calls to FB-OAuth service.

// This code is inside of a nodejs serverroute (hapijs)
// we have a response object `reply` in scope from hapi-route

var HapiJSEndpoint = function(request, reply) {
  // use the oauth2 lib to get our fbLogin and make sure person is authenticated
  var fbLoginUrl = oauth2.getAuthorizeUrl({
        redirect_uri: (_buildOAuthRequestUrl(redirectAuthToken, {
          redirect_url: request.url.query.redirect_url // URL callback to the last view
        })),
        state: 'your random string to protect against cross-site request forgery attacks'
  });

  // Now we use our own Ajax/Request library from within our server route callback
  // This is our own internal request library
  Api.facebookOAUTH.request('facebookAuthorize',
      {'url': (fbLoginUrl + '&scope=facebook-permissions')},
      {headers: {'user-agent': request.headers['user-agent']}},
      // callback handler we are executing for this request
      function(response, headers) {
        // response is our callback handler from facebook oauth service
        if(response.statusCode === 302){
          // FB oauth gives us the required location from our header
          // and can return that link back via hapi's `reply.redirect`
          return reply.redirect(headers.location);
        } else {
          log('OAuth BlewUp', response.statusCode)
        }
      }
    );
}; //< End HapiJS server route handler

Hope this helps abit.