API - Getting Started

Getting Started

The UserVoice API exposes the core end-user and admin functionality of UserVoice to make it easy for you to build client applications or integrations with your own systems.

Create an API client

Before you can make any requests you need to create an API client which will give you a consumer KEY and SECRET.

If you've ever used an API before you can think of the client as your API KEY. It's required to help identify your application whether that be a web application, a server-side script that does some backend integration or a piece of Javascript that pulls down the ideas on your forum.

A quick overview of the fields:

• Name - It's there to help you remember what this API Key was intended for.
• Trusted? - A number of 2-legged OAuth endpoints require a trusted client to work. Do NOT check this if your API Key will be stored in an insecure environment (ex: Javascript or compiled application that end-users download)!
• Application URL (optional) - URL of your web application that's using the UserVoice API.
  This is only relevant if your client is a web application that will require users to authorize its access to their UserVoice data.
• Callback URL (optional) - URL in your web application where users should be returned to after they authorize access to their UserVoice data.
  This is only relevant if your client is a web application that will require users to authorize its access to their UserVoice data.

Now that you have a client go ahead and copy your KEY and SECRET and we're ready to move on to making some actual requests!

Review the available API endpoints

I'd suggest quickly familiarizing yourself with the API references and then coming back here to figure out how to make an actual request.

Making an API request

There are three types of requests:

1. Unauthenticated Requests - Requests you can make without any authentication other than passing your API Key. ex: Retrieving ideas or comments from a public forum.
2. 3-legged OAuth requests - Requests made on the behalf of a user (see any API endpoints marked as requiring a User or Admin). ex: Voting on an idea, Creating a comment, Responding to a idea..
3. 2-legged OAuth requests - Requests made on behalf of the client not on behalf of any specific user (see any API endpoints marked as requiring a Trusted Client) ex: Retrieving all users for a site, Getting a list of ideas for a private forum.

The first scenario is pretty straightforward the other two require the use of OAuth and can be a bit tricky if you've never used OAuth before.

Option A : Unauthenticated requests

Making an unauthenticated request is very simple. You simply need to pass your KEY to the API via the client parameter. For example:

e.g GET http://youraccount.uservoice.com/forums/1/suggestions.json?client=XXXXX

Option B : 3-Legged OAuth requests

In this scenario all actions take place on behalf of a user. There are two options to getting authorization to perform actions:

• There is the standard web authentication system (OAuth 1.0a) in which you redirect an existing user to UserVoice for them to authorize a token that grants your application access to perform actions on their behalf in UserVoice. This is particularly suitable to building integrations between UserVoice and other web applications.
• You can authorize your users by passing an Single Sign-On (SSO) token.

For the former you'll follow the standard OAuth dance:

1. Retrieve a Request Token
2. Redirect the user to UserVoice to authorize your application
3. The user is redirected to the Callback URL you defined in your Client
4. Exchange the Request Token for an Access Token
5. Make requests using the AccessToken

Now if you already have an SSO token for your users you can skip steps 2 and 3:

1. Retrieve a Request Token
2. Exchange the Request Token for an Access Token by passing a valid SSO token via the sso parameter to https://uservoice.uservoice.com/api/v1/oauth/authorize.json
3. Make requests using the AccessToken

Going into details about specific parameters, request signing and the other intricacies of OAuth are outside the scope of this document. Luckily OAuth is a standard not something we just made up so there are a number of resources and libraries out there that will do a lot of heavy lifting for you. Here's a good starting point:

• Linked In OAuth Zero to Hero
• Heuniverse Beginners Guide to OAuth

Option C : 2-Legged OAuth requests

In this scenario there is no user involved in the OAuth dance. You simply create an access token from your consumer and then make requests against the API. This is particularly suitable for creating scripts and performing routine backup and administration.

You can not act on behalf of a user using 2-Legged OAuth and many of the endpoints will require that your client be trusted (see 'Creating an API client').

Parting Thoughts

A few things to keep in mind as you embark on your journey:

1. Private forums, or any content in a private forum, will not be returned unless you're logged in with a user that has access to view that forum.
2. User emails will only be returned if you're authenticating with admin privileges.
3. You can only UPDATE an item if you're the user that created it.
4. SHOW endpoints will return more data than LIST.
5. AccessToken's do not expire. You're free to store them (securely) and use them for all future API requests
6. OAuth libraries will by default connect to to the standard OAuth endpoints located at http://uservoice.uservoice.com/oauth/* which are slightly different than the OAuth endpoints at http://uservoice.uservoice.com/api/v1/oauth/* which you need to use if you go the SSO route.