818 lines (758 with data), 27.6 kB
#%RAML 0.8
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
#
#
# https://github.com/mulesoft/api-designer is a useful tool to edit this file
# web version http://mulesoft.github.io/api-designer/
# version that works well with local files: https://github.com/sichvoge/api-designer-fs but you must change git:// to https:// in its package.json before `npm install`
---
title: Apache Allura
version: 1
baseUri: https://{domain}/rest
securedBy: [null, oauth_1_0]
resourceTypes: !include resourceTypes.yaml
traits: !include traits.yaml
securitySchemes: !include securitySchemes.yaml
baseUriParameters:
domain:
description: "The website domain"
example: "forge-allura.apache.org"
default: "forge-allura.apache.org"
documentation:
- title: API Overview
content: !include docs.md
/auth:
description: |
Authorization related APIs. See also OAuth
/tools/{tool_type}:
uriParameters:
tool_type:
type: string
example: git
type: {
generic: {
example: !include examples/auth-tools.json,
schema: !include schemas/auth-tools.json
}
}
get:
description: |
List tools (e.g. "git" repos) that the current user is associated with
/oauth:
description: |
See separate docs section for authenticating with the OAuth 1.0 APIs
/{neighborhood}:
description: |
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`.
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:
required: true
type: string
example: create
default: read
enum: [read, admin, create, update, register]
/add_project:
description: |
Create a new project and set its admins, tools and various fields. Limited to admins. currently
post:
body:
application/json:
example: |
{
"name": "Template Test 1",
"shortname": "template-test-1",
"summary": "My summary.",
"description": "My description.",
"admin": "admin1",
"external_homepage": "http://wwww.example.com/test",
"labels": ["label1", "label2"],
"trove_audiences": [
"Information Technology",
"Developers"],
"trove_licenses": [
"Apache License V2.0",
"GNU General Public License version 2.0 (GPLv2)",
"Public Domain"],
"awards": [],
"tool_data": {
"allura": {
"grouping_threshold": 5
}
},
"icon": "https://via.placeholder.com/140x100"
}
/{project}:
description: |
Get or modify existing projects.
uriParameters:
project:
description: The Project short name.
example: "allura"
pattern: ([a-zA-Z0-9-]+)
type: {
project: {
schema: !include schemas/project.json,
example: !include examples/project.json
}
}
/has_access:
type: permission
get:
queryParameters:
perm:
required: true
type: string
example: create
default: read
enum: [read, admin, create, update]
/{scm_tool}:
description: |
Represents a **Git/Hg/SVN tool** repo
displayName: SCM Tool
type: {
generic: {
example: !include examples/scm.json,
schema: !include schemas/scm.json
}
}
uriParameters:
scm_tool:
type: string
example: git
/commits:
description: |
Returns the 25 latest commit logs of the SCM tool
/{rev}:
description: |
Represents the revision ID of a commit from where you want the logs to start.
/{limit}:
description: |
Represents the number of commits you want to get from the log.
/{wiki}:
description: |
Represents the **Wiki Tool**.
type: {
generic: {
example: !include examples/wiki.json,
schema: !include schemas/wiki.json
}
}
uriParameters:
wiki:
type: string
example: wiki
/{title}:
type: {
generic: {
example: !include examples/page.json,
schema: !include schemas/page.json
}
}
uriParameters:
title:
type: string
example: Home
get:
description: |
returns a JSON representation of a page
post:
description: |
Creates or updates the titled page.
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
text:
description: |
Page text.
type: string
labels:
description: |
Comma-separated list of page labels.
type: string
/has_access:
type: permission
get:
queryParameters:
perm:
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**.
type: {
generic: {
example: !include examples/tickets.json,
schema: !include schemas/tickets.json
}
}
displayName: Tracker Url
uriParameters:
tracker:
type: string
example: tickets
get:
is: [pageable]
description: |
Get a list of tickets
/{ticketNumber}:
type: {
generic: {
example: !include examples/ticket.json,
schema: !include schemas/ticket.json
}
}
displayName: Ticket Number
uriParameters:
ticketNumber:
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:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
access_token:
description: "The access token provided by the authentication application"
required: true
type: string
ticket_form.summary:
description: Ticket title
type: string
required: false
ticket_form.description:
description: ticket description
type: string
required: false
ticket_form.assigned_to:
type: string
required: false
description: username of ticket assignee
ticket_form.labels:
type: string
required: false
description: comma-separated list of ticket labels
ticket_form.attachment:
type: file
description: (optional) attachment
required: false
ticket_form.custom-field-name:
description: custom field value
type: string
required: false
/search:
type: {
searchableCollection: {
queryParamName: q,
queryParamExample: 'example',
schema: !include schemas/searchedTickets.json,
example: !include examples/searchedTickets.json
}
}
is: [ pageable]
/new:
description: |
Creates a new ticket.
post:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
access_token:
description: "The access token provided by the authentication application"
required: true
type: string
ticket_form.summary:
description: Ticket title
type: string
required: false
ticket_form.description:
description: ticket description
type: string
required: false
ticket_form.assigned_to:
type: string
required: false
description: username of ticket assignee
ticket_form.labels:
type: string
required: false
description: comma-separated list of ticket labels
ticket_form.attachment:
type: file
description: (optional) attachment
required: false
ticket_form.custom_field_name:
description: custom field value
type: string
required: false
/_discuss/thread/{threadId}:
uriParameters:
threadId:
type: string
example: f78b98a0
get:
description: |
returns summary information about a thread, including the posts in a thread
is: [ bearerAuth, pageable ]
/{slug}:
uriParameters:
slug:
type: string
example: 9133
get:
description: |
returns detailed information about a post
is: [ bearerAuth ]
/reply:
description: |
create a threaded reply to the given post
post:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
text:
description: the text of the reply
example: |
I *agree* with you.
required: true
type: string
/new:
description: |
create a post in the given thread
post:
is: [ bearerAuth ]
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
/has_access:
type: permission
get:
queryParameters:
perm:
required: true
type: string
example: post
default: read
enum: [admin, configure, moderate, post, unmoderated_post, read, create, delete, update, save_searches]
/{discussion}:
description: |
Represents the **Discussion Tool**.
type: {
generic: {
schema: !include schemas/discussion.json,
example: !include examples/discussion.json
}
}
displayName: Discussion
uriParameters:
discussion:
type: string
example: "discussion"
get:
description: |
Returns a list of forums, including name, description, num_topics, and last_post details
is: [pageable]
/{forum}:
description: |
Represents a forum within a Discussion tool.
type: {
generic: {
example: !include examples/forum.json,
schema: !include schemas/forum.json
}
}
displayName: forum
uriParameters:
forum:
type: string
example: general
get:
is: [pageable]
description: |
returns a limited list of topics in the forum, with fields for subject, num_replies, API URL, and last_post
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.
/thread/{thread}:
description: |
Represents a thread of posts.
get:
is: [pageable, bearerAuth]
description: |
returns a 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"
/has_access:
type: permission
get:
queryParameters:
perm:
required: true
type: string
example: post
default: read
enum: [admin, configure, moderate, post, unmoderated_post, read]
/{blog}:
type: {
generic: {
example: !include examples/blog.json,
schema: !include schemas/blog.json
}
}
description: |
Represents the **Blog tool**
displayName: Blog
uriParameters:
blog:
type: string
example: blog
get:
description: |
Returns a list of posts, including title and API url.
post:
description: |
Creates a new blog post.
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
title:
description: |
The title of the post.
type: string
example: New API docs released!
text:
description: |
The text of the post.
type: string
example: Lots of text here describing apis!\nThat is all.
labels:
description: |
Labels of the post -- comma seperated strings
type: string
example: api,development
state:
description: |
Draft or published.
enum: [draft, published]
type: string
example: published
/{year}/{month}/{title}:
description: Represents a blog post entry.
type: {
generic: {
example: !include examples/blogPost.json,
schema: !include schemas/blogPost.json
}
}
displayName: Blog Post
uriParameters:
year:
type: number
example: 2015
month:
type: string
example: 04
title:
type: string
example: project-insights
post:
description: |
Updates an existing blog post.
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
title:
description: |
The title of the post.
type: string
text:
description: |
The text of the post.
type: string
labels:
description: |
Labels of the post -- comma seperated strings
type: string
state:
description: |
Draft or published.
enum: [draft, published]
type: string
/has_access:
type: permission
get:
queryParameters:
perm:
required: true
type: string
example: post
default: read
enum: [admin, configure, moderate, post, unmoderated_post, read, write]
/{link}:
description: |
Represents the External Link tool.
type: {
generic: {
example: !include examples/link.json,
schema: !include schemas/link.json
}
}
get:
description: |
Returns the existing url.
post:
description: |
Updates the url. *authentication required*.
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
url:
description: |
The url you would like to update to.
type: string
example: http://google.com
/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}*
is: [ bearerAuth ]
/export_status:
description: |
Check status of a bulk export job
get:
description: |
Returns status: busy or ready
is: [ bearerAuth ]
/{tool}/webhooks:
type: {
typedCollection: {
example: !include examples/webhooks.json,
schema: !include schemas/webhooks.json
}
}
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/
get:
description: |
Returns the list of webhooks
/{type}:
uriParameters:
type:
example: repo-push
enum: [repo-push]
description: |
Allura supports one type of webhook for the moment - repo-push, triggered when a repository receives new commits. It is supported for Git, Mercurial and SVN repositories.
post:
description: |
Create a new webhook.
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
url:
description: |
The url to call when the the webhook is triggered.
required: true
type: string
/{id}:
type: {
generic: {
example: !include examples/webhook.json,
schema: !include schemas/webhook.json
}
}
uriParameters:
id:
type: string
description: |
Unique identifier for a webhook.
get:
description: |
View a webhook
post:
description: |
Update an existing webhook
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
url:
description: |
The url to call when the the webhook is triggered.
required: true
type: string
secret:
description: |
Optionally supply your own secret.
Note: DO NOT ever expose your secret!
required: false
type: string
delete:
is: [ bearerAuth ]
description: |
Delete an existing webhook
/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
post:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
tool:
description: Tool name that you want to install.
example: tickets
enum: [tickets, link, git, svn, mercurial, blog, discussion, subproject, wiki]
required: true
type: string
mount_point:
description: |
The section of the url relative to your project. For example: /p/your_project/{mount_point}
example: git
type: string
required: true
mount_label:
description: |
How your tool will be displayed in your project (like a "nice name" for the tool).
example: Git
type: string
required: true
order:
type: string
enum: [first, last, alpha_tool]
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")
/mount_order:
description: |
Save tool/subproject order for multiple tools at once. *Authentication Required*.
post:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
1:
description: Mount point name for the first position.
example: tickets
type: string
2:
description: Mount point name for the second position.
example: our-news
type: string
3:
description: Mount point name for the third position.
example: documentation
type: string
4...:
description: Etc.
/configure_tool_grouping:
description: |
Set the nav bar grouping threshold. *Authentication Required*.
post:
is: [ bearerAuth ]
body:
application/x-www-form-urlencoded:
formParameters:
grouping_threshold:
description: Value for the grouping threshold.
example: 1
type: number
/installable_tools:
description: |
List of installable tools and their default options. *Authentication Required*.
get:
is: [ bearerAuth ]
/admin_options:
description: |
List of links to admin pages or modal content, for a specific tool. *Authentication Required*.
get:
is: [ bearerAuth ]
queryParameters:
mount_point:
type: string
description: |
The mount point to specify which tool.
/u/{username}:
description: |
Represents a user. This returns a project-like response, since users all automatically have a personal project. Like a project, any tool within a user-project is available through the API as well at /u/{username}/{tool}
Most often you'll use the /profile suffix to return user data.
type: {
generic: {
example: !include examples/user.json,
schema: !include schemas/user.json
}
}
/profile:
description: |
A user profile
type: {
generic: {
example: !include examples/userProfile.json,
schema: !include schemas/userProfile.json
}
}
/notification:
description: |
Get current Site Notification
get:
queryParameters:
cookie:
description: site-notification cookie value
example: "56a111736c4ff90011b9f932-1-False"
url:
description: page where notification will be shown
example: "/p/test-project"
tool_name:
description: tool's name for current page
example: "Git"