[0ce187]: / Allura / docs / api-rest / api.raml  Maximize  Restore  History

Download this file

808 lines (750 with data), 27.4 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.
#
#
# http://apiworkbench.com/ is a useful tool to edit this file
---
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

/{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:
            displayName: Permission
            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:
              displayName: Permission
              required: true
              type: string
              example: create
              default: read
              enum: [read, admin, create, update]

      /{scm_tool}:
        description: |
          Represents the **Git/Hg/SVN tool** and returns the commit count.

        displayName: SCM Tool
        uriParameters:
          scm_tool:
            displayName: Name of 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
          }
        }

        displayName: Wiki
        uriParameters:
         wiki:
           displayName: Wiki Name
           type: string
           example: wiki


        /{title}:
          type: {
            generic: {
              example: !include examples/page.json,
              schema: !include schemas/page.json
              }
            }

          displayName: Title
          uriParameters:
           title:
             displayName: Wiki 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:
                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**.
        type: {
          generic: {
            example: !include examples/tickets.json,
            schema: !include schemas/tickets.json
            }
          }
        displayName: Tracker Url
        uriParameters:
         tracker:
           displayName: Tracker Name
           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:
             displayName: Thread ID
             type: string
             example: f78b98a0

          get:
            description: |
              returns summary information about a thread, including the posts in a thread
            is: [ bearerAuth, pageable ]
          /{slug}:
            uriParameters:
             slug:
               displayName: 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:
                displayName: Permission
                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:
           displayName: Discussion Tool Name
           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:
             displayName: Forum Name
             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:
                displayName: Permission
                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:
           displayName: Blog Name
           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:
               displayName: Year
               type: number
               example: 2015
             month:
               displayName: Month
               type: string
               example: 04
             title:
               displayName: 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:
                displayName: Permission
                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"