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/13 22:01:58 UTC
[04/11] allura git commit: [#6797] first round of some more changes
[#6797] first round of some more changes
* specify which types are valid for each has_access endpoint
* add/update a few descriptions
* add a few missing get: sections
* remove _discuss endpoing which will be removed from code soon
* make user-profile stuff anchored to /u/ neighborhood
* remove old unused permission type
Project: http://git-wip-us.apache.org/repos/asf/allura/repo
Commit: http://git-wip-us.apache.org/repos/asf/allura/commit/0e133c5d
Tree: http://git-wip-us.apache.org/repos/asf/allura/tree/0e133c5d
Diff: http://git-wip-us.apache.org/repos/asf/allura/diff/0e133c5d
Branch: refs/heads/db/6797
Commit: 0e133c5dd65b8a1bbf88d08d8a60f22d490b443c
Parents: 247ee2a
Author: Dave Brondsema <da...@brondsema.net>
Authored: Mon Aug 10 16:16:22 2015 -0400
Committer: Dave Brondsema <da...@brondsema.net>
Committed: Tue Aug 11 12:03:51 2015 -0400
----------------------------------------------------------------------
Allura/docs/api-rest/api.raml | 289 ++++++++++++++++-----------
Allura/docs/api-rest/resourceTypes.yaml | 32 +--
Allura/docs/api-rest/traits.yaml | 19 +-
3 files changed, 179 insertions(+), 161 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/allura/blob/0e133c5d/Allura/docs/api-rest/api.raml
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/api.raml b/Allura/docs/api-rest/api.raml
index b22c117..749e321 100755
--- a/Allura/docs/api-rest/api.raml
+++ b/Allura/docs/api-rest/api.raml
@@ -17,51 +17,70 @@ baseUriParameters:
/{neighborhood}:
description: |
- Neighborhoods are groups of logically related projects, which have the same default options.
-
+ Neighborhoods are groups of logically related projects, which have the same default options.
+
uriParameters:
neighborhood:
example: p
description: |
- Allura has two default neighborhoods: **“Projects”** `/p` and **“Users”** `/u`.
+ Allura has two default neighborhoods: **“Projects”** `/p` and **“Users”** `/u`.
More information can be found [here](https://forge-allura.apache.org/docs/getting_started/using.html?highlight=neighborhood#what-are-neighborhoods)
-
+
/has_access:
type: permission
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: create
+ default: read
+ enum: [read, admin, create, update, register]
+
/{project}:
description: |
Get or modify existing projects.
uriParameters:
project:
- description: "The Apache Allura Project."
+ description: The Project short name.
example: "allura"
pattern: ([a-zA-Z]+)
-
- type: {
- project: {
+
+ type: {
+ project: {
schema: !include schemas/project.json,
example: !include examples/project.json
}
}
-
+
/has_access:
type: permission
-
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: create
+ default: read
+ enum: [read, admin, create, update]
+
/{link}:
description: |
Represents the External Link tool.
- type: {
+ type: {
tool: {
example: !include examples/link.json,
schema: !include schemas/link.json
}
}
-
+
get:
description: |
Returns the existing url.
-
+
post:
description: |
Updates the url. *authentication required*.
@@ -73,9 +92,9 @@ baseUriParameters:
The url you would like to update to.
type: string
example: http://google.com
-
+
/{blog}:
- type: {
+ type: {
tool: {
example: !include examples/blog.json,
schema: !include schemas/blog.json
@@ -83,14 +102,14 @@ baseUriParameters:
}
description: |
Represents the **Blog tool**
-
+
displayName: Blog
uriParameters:
blog:
displayName: Blog Name
type: string
example: blog
-
+
get:
description: |
Returns a list of posts, including title and API url.
@@ -127,8 +146,9 @@ baseUriParameters:
enum: [draft, published]
type: string
example: published
-
+
/{year}/{month}/{title}:
+ description: Represents a blog post entry.
type: {
tool: {
example: !include examples/blogPost.json,
@@ -149,7 +169,7 @@ baseUriParameters:
displayName: Title
type: string
example: project-insights
-
+
post:
description: |
Updates an existing blog post.
@@ -173,10 +193,19 @@ baseUriParameters:
Draft or published.
enum: [draft, published]
type: string
-
+
/has_access:
type: permission
-
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: post
+ default: read
+ enum: [admin, configure, moderate, post, unmoderated_post, read, write]
+
/{forum}:
description: |
A list of forums
@@ -186,7 +215,7 @@ baseUriParameters:
schema: !include schemas/page.json
}
}
-
+
displayName: forum
uriParameters:
forum:
@@ -195,19 +224,30 @@ baseUriParameters:
example: general
description: |
Returns a list of forums, including name, description, num_posts, API URL, and last_post details
-
+
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.
-
+
/forum:
description: |
returns a limited list of topics in the forum, with fields for subject, num_replies, API URL, and last_post
+ get:
/{slug}:
description: |
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"
-
+ get:
+
/has_access:
type: permission
-
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: post
+ default: read
+ enum: [admin, configure, moderate, post, unmoderated_post, read]
+
/{discussion}:
description: |
Represents the **Discussion Tool**.
@@ -215,17 +255,17 @@ baseUriParameters:
tool: {
schema: !include schemas/discussion.json,
example: !include examples/discussion.json
-
+
}
}
-
+
displayName: Discussion
uriParameters:
discussion:
displayName: Discussion Name
type: string
example: "discussion"
-
+
/{forum}:
type: {
tool: {
@@ -233,17 +273,17 @@ baseUriParameters:
schema: !include schemas/page.json
}
}
-
+
displayName: forum
uriParameters:
forum:
displayName: Forum Name
type: string
example: general
-
+
/has_access:
type: permission
-
+
/{wiki}:
description: |
Represents the **Wiki Tool**.
@@ -253,15 +293,15 @@ baseUriParameters:
schema: !include schemas/wiki.json
}
}
-
+
displayName: Wiki
uriParameters:
wiki:
displayName: Wiki Name
type: string
example: wiki
-
-
+
+
/{title}:
type: {
tool: {
@@ -269,7 +309,7 @@ baseUriParameters:
schema: !include schemas/page.json
}
}
-
+
displayName: Title
uriParameters:
title:
@@ -293,11 +333,20 @@ baseUriParameters:
description: |
Comma-separated list of page labels.
type: string
-
-
+
+
/has_access:
type: permission
-
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: post
+ default: read
+ enum: [admin, configure, moderate, post, unmoderated_post, read, create, delete, edit]
+
/{tracker}:
description: |
Represents the **Ticket Tracker Tool**.
@@ -308,70 +357,65 @@ baseUriParameters:
}
}
is: [pageable]
-
+
displayName: Tracker Url
uriParameters:
tracker:
displayName: Tracker Name
type: string
example: tickets
-
+
get:
is: [pageable]
description: |
Get a list of tickets
-
- /_discuss:
- description: |
- returns summary information about the tool discussion, including the threads in the discussion (there is one thread per ticket)
+
+ /_discuss/thread/{threadId}:
+ uriParameters:
+ threadId:
+ displayName: Thread ID
+ type: string
+ example: f78b98a0
+
get:
-
- /thread/{threadId}:
+ description: |
+ returns summary information about a thread, including the posts in a thread
+ /{slug}:
uriParameters:
- threadId:
- displayName: Thread ID
+ slug:
+ displayName: Slug
type: string
- example: f78b98a0
-
+ example: 9133
get:
description: |
- returns summary information about a thread, including the posts in a thread
- /{slug}:
- uriParameters:
- slug:
- displayName: Slug
- type: string
- example: 9133
- get:
- description: |
- returns detailed information about a post
- /reply:
- description: |
- create a threaded reply to the given post
- post:
- body:
- application/x-www-form-urlencoded:
- formParameters:
- text:
- description: the text of the reply
- example: |
- I *agree* with you.
- required: true
- type: string
- /new:
+ returns detailed information about a post
+ /reply:
description: |
- create a post in the given thread
+ create a threaded reply to the given post
post:
body:
application/x-www-form-urlencoded:
formParameters:
text:
- description: The text of the new post
+ description: the text of the reply
example: |
- This is a new post!
+ I *agree* with you.
required: true
type: string
-
+ /new:
+ description: |
+ create a post in the given thread
+ post:
+ body:
+ application/x-www-form-urlencoded:
+ formParameters:
+ text:
+ description: The text of the new post
+ example: |
+ This is a new post!
+ required: true
+ type: string
+
/search:
type: {
searchableCollection: {
@@ -381,12 +425,13 @@ baseUriParameters:
}
}
is: [ pageable]
-
+
/new:
description: |
Creates a new ticket.
post:
body:
+ # FIXME?
application/x-www-form-urlencoded:
formParameters:
access_token:
@@ -417,13 +462,13 @@ baseUriParameters:
description: custom field value
type: string
required: false
-
+
/{ticketNumber}:
type: {
tool: {
example: !include examples/ticket.json,
schema: !include schemas/ticket.json
-
+
}
}
displayName: Ticket Number
@@ -432,14 +477,15 @@ baseUriParameters:
example: 1
description: |
Get a details of a ticket.
-
+
/save:
description: |
updates an existing ticket
parameters are the same as /rest/p/project_name/mount_point/new
-
+
post:
body:
+ # form?
application/x-www-form-urlencoded:
formParameters:
access_token:
@@ -470,22 +516,31 @@ baseUriParameters:
description: custom field value
type: string
required: false
-
+
/has_access:
type: permission
-
-
+ get:
+ queryParameters:
+ perm:
+ displayName: Permission
+ required: true
+ type: string
+ example: post
+ default: read
+ enum: [admin, configure, moderate, post, unmoderated_post, read, create, delete, update, save_searches]
+
+
/admin:
description: |
Endpoints for **project exporting** and managing **webhooks**
-
+
/export:
description: |
Generates a full bulk export of your tool(s) in the same format as the API for individual access. Authentication required. Here is an [example shell](https://forge-allura.apache.org/p/allura/git/ci/master/tree/scripts/project_export) script using these APIs, suitable to run as a cron job.
post:
description: |
Submits an export job
-
+
**400 Bad Request:** tools parameter not provided or is invalid
**503 Service Unavailable:** an export job is already running
**200 OK:** job submitted. Body will be: *{"status": "in progress", "filename": FILENAME}*
@@ -495,7 +550,7 @@ baseUriParameters:
get:
description: |
Returns status: busy or ready
-
+
/{project}/webhooks:
type: {
typedCollection: {
@@ -506,10 +561,10 @@ baseUriParameters:
is: [secured]
description: |
This is to manage webhooks programatically. See the [Webhook docs](https://forge-allura.apache.org/p/allura/wiki/Webhooks/) for more information.
-
+
The webhook payloads and signature verification method are documented at https://forge-allura.apache.org/p/allura/wiki/Webhooks/
-
-
+
+
/{type}:
uriParameters:
type:
@@ -534,7 +589,7 @@ baseUriParameters:
type: string
description: |
Unique identifier for a webhook.
-
+
get:
description: |
View a webhook
@@ -552,7 +607,7 @@ baseUriParameters:
secret:
description: |
Optionally supply your own secret.
-
+
Note: DO NOT ever expose your secret!
required: false
type: string
@@ -562,7 +617,7 @@ baseUriParameters:
/install_tool:
description: |
Adds a new tool to the project. *Authentication Required*.
-
+
returns dict with two fields:
success: False if error is occurred, otherwise True
info: success or error message
@@ -594,24 +649,24 @@ baseUriParameters:
required: false
description: |
"first", "last", or "alpha_tool" for position with respect to existing tools (or existing tools of the same type for "alpha_tool")
-
- /{username}:
- description: |
- Represents a user (returns a project-like response).
-
- Most often you'll use the /profile suffix to return user data.
- type: {
- tool:{
- example: !include examples/user.json,
- schema: !include schemas/user.json
- }
- }
- /profile:
- description: |
- A user profile
- type: {
- tool:{
- example: !include examples/userProfile.json,
- schema: !include schemas/userProfile.json
- }
- }
\ No newline at end of file
+
+/u/{username}:
+ description: |
+ Represents a user (returns a project-like response).
+
+ Most often you'll use the /profile suffix to return user data.
+ type: {
+ tool:{
+ example: !include examples/user.json,
+ schema: !include schemas/user.json
+ }
+ }
+ /profile:
+ description: |
+ A user profile
+ type: {
+ tool:{
+ example: !include examples/userProfile.json,
+ schema: !include schemas/userProfile.json
+ }
+ }
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/0e133c5d/Allura/docs/api-rest/resourceTypes.yaml
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/resourceTypes.yaml b/Allura/docs/api-rest/resourceTypes.yaml
index 10dcb53..1f7b9f8 100755
--- a/Allura/docs/api-rest/resourceTypes.yaml
+++ b/Allura/docs/api-rest/resourceTypes.yaml
@@ -64,36 +64,7 @@
body:
application/json:
schema: <<schema>>
- delete?:
-- permissionCheck:
- description: |
- This is API to run permission checks.
- It is available on a neighborhood, project and tool level.
-
- This 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.
- get:
- queryParameters:
- user:
- type: string
- example: heiths
- required: true
- description: The username to check
- perm:
- displayName: Permission
- required: true
- type: string
- example: create
- default: read
- enum: ["read", "admin", "create", "update"]
- description: |
- Get permissions for <<resourcePathName>>.
- responses:
- 200:
- body:
- application/json:
- schema: <<schemaItem>>
+ delete?:
- searchableCollection:
get:
queryParameters:
@@ -147,4 +118,3 @@
application/json:
schema: <<schema>>
-
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/allura/blob/0e133c5d/Allura/docs/api-rest/traits.yaml
----------------------------------------------------------------------
diff --git a/Allura/docs/api-rest/traits.yaml b/Allura/docs/api-rest/traits.yaml
index d483810..c1f47c5 100755
--- a/Allura/docs/api-rest/traits.yaml
+++ b/Allura/docs/api-rest/traits.yaml
@@ -50,15 +50,15 @@
- permissionTestable:
description: |
**Endpoints**
- Permissions can be checked at three levels:
+ Permissions can be checked at three levels:
1. **Neighborhood:** `/rest/p/has_access`
2. **Project:** `/rest/p/project_name/has_access`
3. **Tool:** `/rest/p/project_name/mount_point/has_access`
-
- ---
-
+
+ ---
+
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.
-
+
E.g.:
**GET** `/rest/p/test/wiki/has_access?user=admin1&perm=create`
*returns* { result: true }
@@ -70,11 +70,4 @@
type: string
example: heiths
required: true
- description: The username to check
- perm:
- displayName: Permission
- required: true
- type: string
- example: create
- default: read
- enum: ["read", "admin", "create", "update"]
\ No newline at end of file
+ description: The username to check
\ No newline at end of file