| #%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" |
