You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@allura.apache.org by br...@apache.org on 2015/08/20 22:49:33 UTC
[13/14] allura git commit: [#6797] Add user docs and forum json
[#6797] Add user docs and forum json
Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/f2b22c7a
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/f2b22c7a
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/f2b22c7a
Branch: refs/heads/master
Commit: f2b22c7a15afd2380efb85b31e18510e34389bbf
Parents: 2109578
Author: Heith Seewald <hs...@hsmb.local>
Authored: Fri Aug 14 12:10:54 2015 -0400
Committer: Dave Brondsema <da...@brondsema.net>
Committed: Thu Aug 20 16:49:14 2015 -0400
----------------------------------------------------------------------
Allura/docs/api-rest/api.raml | 9 +-
Allura/docs/api-rest/docs.md | 189 ++++++++++++++++++++++++++
Allura/docs/api-rest/examples/forum.json | 32 +++++
Allura/docs/api-rest/schemas/forum.json | 76 +++++++++++
4 files changed, 303 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/allura/blob/f2b22c7a/Allura/docs/api-rest/api.raml
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/api.raml b/Allura/docs/api-rest/api.raml
index 9a55249..60cfe94 100755
--- a/Allura/docs/api-rest/api.raml
+++ b/Allura/docs/api-rest/api.raml
@@ -15,6 +15,10 @@ baseUriParameters:
example: "forge-allura.apache.org"
default: "forge-allura.apache.org"
+documentation:
+ - title: Api Overview
+ content: !include docs.md
+
/{neighborhood}:
description: |
Neighborhoods are groups of logically related projects, which have the same default options.
@@ -341,9 +345,8 @@ baseUriParameters:
Represents a forum within a Discussion tool.
type: {
generic: {
- # FIXME
- example: !include examples/page.json,
- schema: !include schemas/page.json
+ example: !include examples/forum.json,
+ schema: !include schemas/forum.json
}
}
displayName: forum
http://git-wip-us.apache.org/repos/asf/allura/blob/f2b22c7a/Allura/docs/api-rest/docs.md
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/docs.md b/Allura/docs/api-rest/docs.md
new file mode 100755
index 0000000..dd22b83
--- /dev/null
+++ b/Allura/docs/api-rest/docs.md
@@ -0,0 +1,189 @@
+#### Basic API architecture
+
+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.
+
+
+#### Permissions
+
+This is API to run permission checks. It is available on a neighborhood, project and tool level.
+
+It is only available to users that have 'admin' permission for corresponding neighborhood/project/tool.
+It requires `user` and `perm` parameters and will return JSON dict with `result` key, which contains boolean value, indicating if given `user` has `perm` permission to the neighborhood/project/tool.
+
+
+
+#### Project Export
+
+Generates a full bulk export of your tool(s) in the same format as the API for individual access.
+Authentication required.
+
+An example shell script using these APIs, suitable to run in a cron, is at <https://forge-allura.apache.org/p/allura/git/ci/master/tree/scripts/project_export>
+
+
+
+
+#### DOAP (Description of a Project)
+
+[DOAP](http://en.wikipedia.org/wiki/DOAP) is an RDF/XML specification for "Description of a Project"
+
+Project information is available in DOAP format with additional custom RDF fields at /rest/p/*project_name*?doap
+
+
+#### User
+
+This is a user's personal project, so it contains the same information as a project, although many fields may not be useful.
+The `profile_api_url` field is a link to the user's profile endpoint which is documented next.
+
+
+#### Webhooks
+
+This allows you to manage webhooks programatically. See https://forge-allura.apache.org/p/allura/wiki/Webhooks/ for using a webhook.
+
+
+#### Authenticating requests
+
+In order to use the API for authenticated actions, you should use the OAuth account page 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.
+
+You can also use your normal browser session as authentication for the API. This is useful for manually testing API calls or for in-browser applications (such as extensions or user-scripts). It is not recommended for programatic access, however, as it would require you to store your account username and password, and thus cannot be easily managed or revoked.
+
+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
+
+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` URL parameter, `access_token` POST form field, or http header like `Authorization: Bearer MY_BEARER_TOKEN`.
+
+Note, however, that to use bearer tokens, you *must* use HTTPS/SSL for the request.
+
+Simple URL example to access a private ticket:
+
+https://sourceforge.net/rest/p/theproject/tickets/35/?access_token=MY_BEARER_TOKEN
+
+Python code example:
+
+~~~~~
+ import requests
+ from pprint import pprint
+
+ BEARER_TOKEN = '<bearer token from oauth page>'
+
+ r = requests.post('https://sourceforge.net/rest/p/test-project/new', 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 your application to be able to use the API on behalf of another user, that 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`.
+
+~~~~~
+ 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:
+
+~~~~~
+ 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
+~~~~~
http://git-wip-us.apache.org/repos/asf/allura/blob/f2b22c7a/Allura/docs/api-rest/examples/forum.json
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/examples/forum.json b/Allura/docs/api-rest/examples/forum.json
new file mode 100644
index 0000000..a20c1c4
--- /dev/null
+++ b/Allura/docs/api-rest/examples/forum.json
@@ -0,0 +1,32 @@
+{
+ "topic": {
+ "_id": "a7528751",
+ "posts": [
+ {
+ "text": "How to fix anything!",
+ "attachments": [
+ ],
+ "author": "root",
+ "timestamp": "2015-07-20 16:36:18.019000",
+ "last_edited": null,
+ "slug": "c920",
+ "subject": "Tech Support"
+ },
+ {
+ "text": "fdas",
+ "attachments": [
+ ],
+ "author": "hs2",
+ "timestamp": "2015-07-22 15:41:58.522000",
+ "last_edited": null,
+ "slug": "b8fa",
+ "subject": "Tech Support"
+ }
+ ],
+ "discussion_id": "5568f6684d212236d1eaed07",
+ "subject": "Tech Support"
+ },
+ "count": 2,
+ "limit": 25,
+ "page": 0
+}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/f2b22c7a/Allura/docs/api-rest/schemas/forum.json
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/schemas/forum.json b/Allura/docs/api-rest/schemas/forum.json
new file mode 100644
index 0000000..7c67c61
--- /dev/null
+++ b/Allura/docs/api-rest/schemas/forum.json
@@ -0,0 +1,76 @@
+{
+ "$schema": "http://json-schema.org/draft-04/schema#",
+ "id": "/",
+ "type": "object",
+ "properties": {
+ "topic": {
+ "id": "topic",
+ "type": "object",
+ "properties": {
+ "_id": {
+ "id": "_id",
+ "type": "string"
+ },
+ "posts": {
+ "id": "posts",
+ "type": "array",
+ "items": {
+ "id": "1",
+ "type": "object",
+ "properties": {
+ "text": {
+ "id": "text",
+ "type": "string"
+ },
+ "attachments": {
+ "id": "attachments",
+ "type": "array",
+ "items": {}
+ },
+ "author": {
+ "id": "author",
+ "type": "string"
+ },
+ "timestamp": {
+ "id": "timestamp",
+ "type": "string"
+ },
+ "last_edited": {
+ "id": "last_edited",
+ "type": "null"
+ },
+ "slug": {
+ "id": "slug",
+ "type": "string"
+ },
+ "subject": {
+ "id": "subject",
+ "type": "string"
+ }
+ }
+ }
+ },
+ "discussion_id": {
+ "id": "discussion_id",
+ "type": "string"
+ },
+ "subject": {
+ "id": "subject",
+ "type": "string"
+ }
+ }
+ },
+ "count": {
+ "id": "count",
+ "type": "integer"
+ },
+ "limit": {
+ "id": "limit",
+ "type": "integer"
+ },
+ "page": {
+ "id": "page",
+ "type": "integer"
+ }
+ }
+}
\ No newline at end of file