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