Allura API

• APIs at SourceForge
  • URL Endpoints
    • Project
    • Wiki
    • Discussion Forums
    • Tracker
    • Blog
    • External Link
  • Authenticating requests
  • OAuth With Bearer Tokens (Coming Soon)
  • OAuth 1.0 Application Authorization (Third-Party Apps)

APIs at SourceForge

URL Endpoints

All url endpoints are prefixed with /rest/ and the path to the project and tool. For example, in order to access a wiki installed in the 'test' project with the mount point 'docs' the API endpoint would be /rest/p/test/docs . All endpoints below assume this prefix.

Project

Endpoint: /rest/p/projectname/

• GET: returns the following fields
  • _id: internal id string
  • name: string
  • shortname: string
  • url: URL to project
  • summary: one-line string
  • short_description: string
  • external_homepage: URL
  • labels: list of strings
  • private: boolean
  • status: string (active, moved, abandoned, deleted)
  • moved_to_url: URL, if status is "moved"
  • preferred_support_tool: string (corresponding to mount point)
  • preferred_support_url: full URL if preferred_support_tool is set to "_url"
  • socialnetworks: list of dicts having socialnetwork and accounturl values
  • icon_url: URL
  • tools: list of tools installed on the project
    • name: specifies the type of tool
    • label: the label specified by the project admin
    • mount_point: the URL component of the tool. It can be used for constructing further API queries to specific tools, as follows.
  • categories: group of project categorizations (developmentstatus, topic, language, etc) with each individual category containing:
    • fullpath: string, category hierarchy
    • fullname: string, name of category
    • shortname: string, short form of category
    • id: int, unique identifier
  • screenshots
    • url: URL to image
    • caption: string
    • thumbnail_url: URL to smaller thumbnail version of image
  • developers: list of project members
    • url: URL to user profile page
    • name: public full name
    • username: username string

Wiki

Endpoint: prefix/

• GET prefix/ - returns a list of page titles
• GET prefix/title - returns a JSON representation of a page
• POST prefix/title - creates or updates the titled page
  • parameter text: page text
  • parameter labels: comma-separated list of page labels

Discussion Forums

Endpoint: prefix/

• GET prefix/ - returns a list of forums, including name, description, num_posts, API URL, and last_post details
• GET prefix/forum/ - returns a limited list of topics in the forum, with fields for subject, num_replies, API URL, and last_post
• GET prefix/forum/thread/slug/ - returns a limited list of posts in the thread, with fields for author, text, and timestamp. Nested posts (i.e. a reply to a post) can be determined by the slug structure. For example, "slug": "0a0b/9f00" is a reply to the post with "slug": "0a0b"

To view more than 100 threads, or 100 posts in a thread, use the pagination support of the API by adding ?page=1 etc. to the URL.

Tracker

Endpoint: prefix/

• GET prefix/ - returns a list of ticket numbers
• GET prefix/search?q=query - returns search results. Query is same syntax as the non-API ticket search
• GET prefix/number - returns a JSON representation of a ticket
• POST prefix/new - creates a new ticket
  • parameter ticket_form.summary - ticket title
  • parameter ticket_form.description - ticket description
  • parameter ticket_form.status - ticket status
  • parameter ticket_form.assigned_to - username of ticket assignee
  • parameter ticket_form.labels - comma-separated list of ticket labels
  • parameter ticket_form.attachment - (optional) attachment
  • parameter ticket_form.custom field name - custom field value
• POST prefix/number/save - updates an existing ticket
  • parameters are the same as prefix/new

Endpoint: prefix/_discuss/

• GET prefix/_discuss/ - returns summary information about the tool discussion, including the threads in the discussion (there is one thread per ticket)
• GET prefix/_discuss/thread/thread id/ - returns summary information about a thread, including the posts in a thread
• GET prefix/_discuss/thread/thread id/post slug/ - returns detailed information about a post
• POST prefix/_discuss/thread/thread id/new - create a post in the given thread
  • parameter text - the text of the post
• POST prefix/_discuss/thread/thread id/post slug/reply - create a threaded reply to the given post
  • parameter text - the text of the reply

Blog

Endpoint: prefix/

• GET prefix/ - returns a list of posts, including title and API url
• GET prefix/year/month/title - returns a JSON representation of a post
• POST prefix/ - creates a post
  • parameter title - the title of the post
  • parameter text - the text of the post
  • parameter labels - labels of the post
  • parameter state - 'draft' or 'published'
• POST prefix/year/month/title - updates an existing post
  • parameter parameters:
  • parameter title - the title of the post
  • parameter text - the text of the post
  • parameter labels - labels of the post
  • parameter state - 'draft' or 'published'

External Link

Endpoint: prefix/

• GET prefix/ - returns the url
• POST prefix/ - updates the url (authentication required)
  • parameter url: the url (for example "http://google.com")

Authenticating requests

In order to use the API for authenticated actions, you must use OAuth 1.0 to create a consumer key for your application. Once you have a consumer key, you must have a SourceForge user (e.g. your own account, if you're writing a single script) authorize your application to act on his or her behalf.

Without authentication, all API requests have the permissions of an anonymous visitor. To view or change anything that requires a login, you must authenticate to the API using OAuth. You must first register for an OAuth consumer token at https://sourceforge.net/auth/oauth/. Once you have registered, you will be be able to see your consumer key and consumer secret, or generate a bearer token, at https://sourceforge.net/auth/oauth/.

OAuth With Bearer Tokens (Coming Soon)

The easiest way to use the API with your own account is to use a bearer token. Once you have generated a bearer token at https://sourceforge.net/auth/oauth/, you just include it in the request to the API via the access_token parameter and your requests will be authenticated. Note, however, that to use bearer tokens, you must use HTTPS/SSL for the request.

:::python
import requests
from pprint import pprint

BEARER_TOKEN = '9a4413b4ee9a1621be8a'

r = requests.post('https://sourceforge.net/rest/p/test-project/new', verify=False, params={
        'access_token': BEARER_TOKEN,
        'ticket_form.summary': 'Test ticket',
        'ticket_form.description': 'This is a test ticket',
        'ticket_form.labels': 'test',
        'ticket_form.custom_fields._my_num': '7',  # custom field with label "My Num"
                                                   # must be created first
    })
if r.status_code == 200:
    print 'Ticket created at: %s' % r.url
    pprint(r.json())
else:
    print 'Error [%s]:\n%s' % (r.status_code, r.text)

OAuth 1.0 Application Authorization (Third-Party Apps)

If you want another user to be able to use your OAuth application to access the API, the user must authorize your application to act on their behalf. This is usually accomplished by obtaining a request token and directing the user authorize the request. The following is an example of how one would authorize an application in Python using the python-oauth2 library. First, run pip install oauth2 and pip install certifi.

:::python
CONSUMER_KEY = '<consumer key from registration>'
CONSUMER_SECRET = '<consumer secret from registration>'
REQUEST_TOKEN_URL = 'https://sourceforge.net/rest/oauth/request_token'
AUTHORIZE_URL = 'https://sourceforge.net/rest/oauth/authorize'
ACCESS_TOKEN_URL = 'https://sourceforge.net/rest/oauth/access_token'

import oauth2 as oauth  # misleading package name, oauth2 implements OAuth 1.0 spec
import certifi
from urllib2 import urlparse
import webbrowser

consumer = oauth.Consumer(CONSUMER_KEY, CONSUMER_SECRET)
client = oauth.Client(consumer)
client.ca_certs = certifi.where()

# Step 1: Get a request token. This is a temporary token that is used for 
# having the user authorize an access token and to sign the request to obtain 
# said access token.

resp, content = client.request(REQUEST_TOKEN_URL, 'GET')
if resp['status'] != '200':
    raise Exception("Invalid response %s." % resp['status'])

request_token = dict(urlparse.parse_qsl(content))

# these are intermediate tokens and not needed later
#print "Request Token:"
#print "    - oauth_token        = %s" % request_token['oauth_token']
#print "    - oauth_token_secret = %s" % request_token['oauth_token_secret']
#print 

# Step 2: Redirect to the provider. Since this is a CLI script we do not 
# redirect. In a web application you would redirect the user to the URL
# below, specifying the additional parameter oauth_callback=<your callback URL>.

webbrowser.open("%s?oauth_token=%s" % (
        AUTHORIZE_URL, request_token['oauth_token']))

# Since we didn't specify a callback, the user must now enter the PIN displayed in 
# their browser.  If you had specified a callback URL, it would have been called with 
# oauth_token and oauth_verifier parameters, used below in obtaining an access token.
oauth_verifier = raw_input('What is the PIN? ')

# Step 3: Once the consumer has redirected the user back to the oauth_callback
# URL you can request the access token the user has approved. You use the 
# request token to sign this request. After this is done you throw away the
# request token and use the access token returned. You should store this 
# access token somewhere safe, like a database, for future use.
token = oauth.Token(request_token['oauth_token'],
    request_token['oauth_token_secret'])
token.set_verifier(oauth_verifier)
client = oauth.Client(consumer, token)
client.ca_certs = certifi.where()

resp, content = client.request(ACCESS_TOKEN_URL, "GET")
access_token = dict(urlparse.parse_qsl(content))

print "Access Token:"
print "    - oauth_token        = %s" % access_token['oauth_token']
print "    - oauth_token_secret = %s" % access_token['oauth_token_secret']
print
print "You may now access protected resources using the access tokens above." 
print

You can then use your access token with the REST API. For instance script to create a wiki page might look like this:

:::python
from urllib import urlencode
import oauth2 as oauth
import certifi

PROJECT='test'

CONSUMER_KEY='<consumer key from app registration>'
CONSUMER_SECRET='<consumer secret from app registration>'

ACCESS_KEY='<access key from previous script>'
ACCESS_SECRET='<access secret from previous script>'

URL_BASE='https://sourceforge.net/rest/'

consumer = oauth.Consumer(CONSUMER_KEY, CONSUMER_SECRET)
access_token = oauth.Token(ACCESS_KEY, ACCESS_SECRET)
client = oauth.Client(consumer, access_token)
client.ca_certs = certifi.where()

response = client.request(
    URL_BASE + 'p/' + PROJECT + '/wiki/TestPage', 'POST',
    body=urlencode(dict(
            text='This is a test page')))
print "Done.  Response was:"
print response