Need Help? Support

Getting Started (Node.js)

This guide will help you create an Express web server that can authorize with the Singly API and fetch data. The code is available in our Node.js/Express skeleton.

Prerequisites

You only need a recent version of Node (we run 0.6.16), which comes with NPM. We like installing it through NVM.

Start a server

Once you have Node installed, starting up is as simple as downloading the code, installing NPM dependencies and running the server.

git clone git://github.com/Singly/nodejs_express_skeleton.git
cd nodejs_express_skeleton
npm install
node app.js

Now navigate to http://localhost:7464/ and you should see the example homepage with a list of services. For all services Singly supports, see the list of service endpoints.

But if you try to access one, you'll get the error

client_id and redirect_uri required

If you haven't already registered an application, do that now on the Application Mangement page. Make sure your settings include the right URLS:

These must match the hostname you're loading the skeleton from, or authorization will fail. For more on using OAuth2 with Singly, see the authorization documentation.

Configure your server

The example uses the the SINGLY_CLIENT_ID and SINGLY_CLIENT_SECRET environment variable. If you have foreman you can set them in a .env file. If not, you can simply set them as local environment variables:

export SINGLY_CLIENT_ID=<clientID>
export SINGLY_CLIENT_SECRET=<clientSecret>

and start the app directly:

node app

clientID and clientSecret are shown on your application settings page after you've registered.

Authorization

After you start your server with the correct client ID and secret, you'll be able to authorize using any of the listed services. That uses the OAuth2 flow, which starts out at a URL like

https://api.singly.com/oauth/authenticate?client_id=YOUR_CLIENT_ID&service=SERVICE&redirect_uri=CALLBACK

where the query parameters are

  • client_id The clientID you used when you started the server
  • service The service the user wants to authorize with, eg. Facebook or Twitter
  • redirect_uri The URL on your server the user is sent back to after they log in to service. This must match the Callback URL you provided in your application settings.

Using the API

Now if you click on a service you've authorized, instead of being asked to log in, you'll be taken to that service's profile summary. If you're quick, you can refresh that page and see the initial sync of your data from that service. The URL we're hitting now is fully documented with the service endpoints and is of the form

https://api.singly.com/services/SERVICE?access_token=TOKEN

where SERVICE is one of the services you just authorized and TOKEN is the token we got back during the code exchange. All API endpoints require the access_token parameter and give back data only for the user associated with that token, except for the /services endpoint which provides a simple list of availble services and the data provided by each.

Go exploring

Now you know how authorization works and how to get data from the Singly API. It's a simple JSON API, so you can access it anywhere you like so long as you have someone's token. To speed you up, there are client packages available for Node and Ruby.

You can also see the shape of the API and explore your own data with the API Explorer.

Extended configuration

If you're running your server somewhere other than localhost, you can set the PORT and HOST environment variables. This hostname must match your appliation settings.

By default, the skeleton runs against https://api.singly.com, but if you're working on your own version of the API, you can provide that too. This is not at all required to run your node example, and to get going you should just use https://api.singly.com.

How'd it go?

We love feedback our this walkthrough and the rest of our documentation. If there was any part of this that was wrong, unclear, or otherwise tripped you up, file an issue or come talk with us live on HipChat.