Use a more common example wiki page name

#%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.
---
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]

    /{project}:
      description: |
        Get or modify existing projects.
      uriParameters:
        project:
          description: The Project short name.
          example: "allura"
          pattern: ([a-zA-Z]+)

      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]

      /{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

        /_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 ]
          /{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

        /search:
          type: {
            searchableCollection: {
            queryParamName: q,
            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

        /{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

        /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: number
               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 ]
        /{project}/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")

/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
        }
      }

#%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.
---
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]

    /{project}:
      description: |
        Get or modify existing projects.
      uriParameters:
        project:
          description: The Project short name.
          example: "allura"
          pattern: ([a-zA-Z]+)

      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]

      /{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: Extensions
          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

        /_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 ]
          /{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

        /search:
          type: {
            searchableCollection: {
            queryParamName: q,
            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

        /{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

        /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: number
               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 ]
        /{project}/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")

/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
        }
      }


Fix definition of discovery/nodes put and add futher responses

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          404:
            description: Not Found
            body:
              text/plain:
/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{node_id}:
    put:
      description: Update descriptor of a particular node, only the name can be changed
      body:
        application/json:
          schema: NodeDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: NodeDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces/{interface_id}:
      get:
        description: Get all modules that provide the specified interface ID
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check

#%RAML 0.8
title: Okapi Core API
version: 2.0
schemas:
  - DeploymentDescriptor: !include DeploymentDescriptor.json
  - LaunchDescriptor: !include LaunchDescriptor.json
  - DeploymentDescriptorList: !include DeploymentDescriptorList.json
  - ModuleDescriptor: !include ModuleDescriptor.json
  - ModuleList: !include ModuleList.json
  - TenantDescriptor: !include TenantDescriptor.json
  - TenantList: !include TenantList.json
  - TenantModuleDescriptor: !include TenantModuleDescriptor.json
  - TenantModuleDescriptorList: !include TenantModuleDescriptorList.json
  - HealthStatus: !include HealthStatus.json
  - HealthStatusList: !include HealthStatusList.json
  - HealthDescriptor: !include HealthDescriptor.json
  - HealthDescriptorList: !include HealthDescriptorList.json
  - NodeDescriptor: !include NodeDescriptor.json
  - NodeDescriptorList: !include NodeDescriptorList.json
  - EnvEntry: !include EnvEntry.json
  - EnvEntryList: !include EnvEntryList.json
  - Permission: !include Permission.json
  - PullDescriptor: !include PullDescriptor.json

/_/deployment/modules:
  description: Deployment service. This is responsible for starting and
    stopping modules.
  post:
    description: Deploy (launch process, start a container, etc) instance of a
      particular service, according to the deployment descriptor.
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the descriptor of the deployed instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all deployed instances
    responses:
      200:
        body:
          application/json:
            schema: DeploymentDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing

  /{instance_id}:
    get:
      description: Retrieve deployment descriptor for a particular instance
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    delete:
      description: shutdown instance
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/discovery/modules:
  description: Discovery service. This is responsible for monitoring
    all instances (deployed) on, possibly many, deployment nodes.
  post:
    description: Register instance under a specified service id
    body:
      application/json:
        schema: DeploymentDescriptor
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      404:
        description: Not Found
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Return all instances
    responses:
      200:
        description: Ok
        headers:
          Location:
            description: URI to the registered instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: DeploymentDescriptorList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: List all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: DeploymentDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    /{instance_id}:
      get:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      put:
        description: Update registration of a specified instance
        responses:
          200:
            body:
              application/json:
                schema: DeploymentDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
      delete:
        description: Remove registration for a given instance
        responses:
          204:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing

/_/discovery/health:
  description: Health service for individual instances
  get:
    description: Get health info for all services
    responses:
      200:
        body:
          application/json:
            schema: HealthDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{service_id}:
    get:
      description: Health for all instances for a particular service
      responses:
        200:
          body:
            application/json:
              schema: HealthDescriptorList
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
    /{instance_id}:
      get:
        description: get health for a particular instance
        responses:
          200:
            body:
              application/json:
                schema: HealthDescriptor
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
/_/discovery/nodes:
  description: Get information about nodes
  get:
    description: Get list of all nodes
    responses:
      200:
        body:
          application/json:
            schema: NodeDescriptorList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  put:
    description: Update descriptor of a particular node, only the name can be changed
    body:
      application/json:
        schema: NodeDescriptor
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: NodeDescriptor
  /{node_id}:
    get:
      description: Get info for one node
      responses:
        200:
          body:
            application/json:
              schema: NodeDescriptor
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:

/_/proxy/modules:
  description: Proxy modules service
  post:
    description: Announce new module to the proxy. Once successful a module
      can be selected for a specific tenant.
    body:
      application/json:
        schema: ModuleDescriptor
    responses:
      201:
        description: Created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created module instance
        body:
          application/json:
            schema: ModuleDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: List all or subset of modules for proxy
    queryParameters:
      filter:
        description: Filter by module ID
        type: string
        required: false
      full:
        description: whether full or compact MD should be returned
        type: boolean
        required: false
      orderBy:
        description: Order by field
        type: string
        required: false
      order:
        description: Order
        enum: [desc, asc]
        required: false
      preRelease:
        description: whether to include modules with pre-release info
        type: boolean
        required: false
    responses:
      200:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{module_id}:
    get:
      description: Retrieve descriptor for a particular module
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
    put:
      description: Update descriptor of a particular module
      body:
        application/json:
          schema: ModuleDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: ModuleDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
    delete:
      description: Remove module descriptor for a particular module, module
        will no longer be selectable by tenants
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/proxy/tenants:
  description: Tenants service
  post:
    description: Create a new tenant
    body:
      application/json:
        schema: TenantDescriptor
    responses:
      201:
        description: Tenant has been created
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
          Location:
            description: URI to the created tenant
        body:
          application/json:
            schema: TenantDescriptor
      400:
        description: Bad Request
        body:
          text/plain:
  get:
    description: List all tenants
    responses:
      200:
        description: List of tenants in a brief format
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: TenantList
  /{tenant_id}:
    get:
      description: Retrieve a tenant
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        404:
          description: Not Found
          body:
            text/plain:
    put:
      description: Update a tenant
      body:
        application/json:
          schema: TenantDescriptor
      responses:
        200:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
          body:
            application/json:
              schema: TenantDescriptor
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    delete:
      description: Remove a tenant
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        403:
          description: Forbidden
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
    /modules:
      post:
        description: Enable a module for tenant. Only the member 'id' from
          TenantModuleDescriptor is used in this operation.
          This call will eventually be replaced by the 'install' service.
        body:
          application/json:
            schema: TenantModuleDescriptor
        responses:
          201:
            description: Created
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
              Location:
                description: URI to the enabled module
            body:
              application/json:
                schema: TenantModuleDescriptor
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
      get:
        description: Get enabled modules for tenant
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
      /{module_id}:
        description: CRUD service for getting module and upgrading module
          for a tenant.
        get:
          description: Look up particular module selection
          responses:
            200:
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
              body:
                application/json:
                  schema: TenantModuleDescriptor
            404:
              description: Not Found
              body:
                text/plain:
        post:
          description: Upgrade a module for a tenant. Enable new module and
            disable current module with new module ID in body and existing ID
            in path.
            This call will eventually be replaced by the 'install' service.
          body:
            application/json:
              schema: TenantModuleDescriptor
          responses:
            201:
              description: Created
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
                Location:
                  description: URI to the enabled module
              body:
                application/json:
                  schema: TenantModuleDescriptor
            400:
              description: Client Error
              body:
                text/plain:
            404:
              description: Not Found
              body:
                text/plain:
            500:
              description: Server Error
              body:
                text/plain:
        delete:
          description: Disable a module for a tenant.
            This call will eventually be replaced by the 'install' service.
          responses:
            204:
              description: Gone
              headers:
                X-Okapi-Trace:
                  description: Okapi trace and timing
            400:
              description: Client Error
              body:
                text/plain:
    /install:
      post:
        description: Enable, disable or upgrade one or more modules for
          tenant. The request body and response body is of the same type
          TenantModuleDescriptorList. This list includes one or more
          modules to be enabled, disabled or upgraded. The request is the
          initial desired changes and the response is the list of changes
          that must be fulfilled to satisfy dependencies.
          This service will eventually partially replace
          /_/proxy/tenants/{tenant}/modules . It also allows
          enabling multiple modules in in one transaction.
          For simulate=true, the response, can be viewed as a recipe for what
          must be deployed (optionally) and enabled/disabled by the existing
          tenants-modules CRUD service.
        queryParameters:
          simulate:
            description: Whether the installation is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        body:
          application/json:
            schema: TenantModuleDescriptorList
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /upgrade:
      post:
        description: Check if newer modules of exist and upgrade for tenant.
          The response is a list of modules that should be enabled, disabled
          or upgraded to perform the upgrade.
        queryParameters:
          simulate:
            description: whether the upgrade is simulated
            type: boolean
          preRelease:
            description: Whether pre-releases should be considered for
              installation.
            type: boolean
        responses:
          200:
            description: OK
            body:
              application/json:
                schema: TenantModuleDescriptorList
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
          400:
            description: Bad Request
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
    /interfaces/{interface_id}:
      get:
        description: Get all modules that provide the specified interface ID
        responses:
          200:
            headers:
              X-Okapi-Trace:
                description: Okapi trace and timing
            body:
              application/json:
                schema: TenantModuleDescriptorList
          400:
            description: Client Error
            body:
              text/plain:
          404:
            description: Not Found
            body:
              text/plain:
          500:
            description: Server error
            body:
              text/plain:
/_/proxy/health:
  description: Check health of modules
  get:
    description: Check health of modules
    responses:
      200:
        description: OK
        body:
          application/json:
            schema: HealthStatusList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      500:
        description: Server Error

/_/proxy/pull/modules:
  description: Pull module descriptors from a remote repository
  post:
    description: Pull modules (i.e. Module Descriptors) from a remote
      repository. The PullDescriptor includes one or more URLs. And
      the operation will try all URLs in order until one succeeds. Hence,
      the URLs should be pointing to identical remote repositories.
    body:
      application/json:
        schema: PullDescriptor
    responses:
      200:
        description: OK
        headers:
          Location:
            description:
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: ModuleList
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/env:
  description: Environment service. Environment variables are system
    variables that allows us to configure modules in a uniform way.
    They can hold fundamental database configuration, etc.
  post:
    description: Add environment entry
    body:
      application/json:
        schema: EnvEntry
    responses:
      201:
        description: Created
        headers:
          Location:
            description: URI to the environment entry instance
          X-Okapi-Trace:
            description: Okapi trace and timing
        body:
          application/json:
            schema: EnvEntry
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  get:
    description: Get list of all environment variables
    responses:
      200:
        body:
          application/json:
            schema: EnvEntryList
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:
  /{id}:
    get:
      description: Get info for one environment variable
      responses:
        200:
          body:
            application/json:
              schema: EnvEntry
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing
        400:
          description: Bad Request
          body:
            text/plain:
        404:
          description: Not Found
          body:
            text/plain:
        500:
          description: Server Error
          body:
            text/plain:
    delete:
      description: Remove environment variable
      responses:
        204:
          headers:
            X-Okapi-Trace:
              description: Okapi trace and timing

/_/version:
  description: Service for getting information about Okapi
  get:
    description: get Okapi version
    responses:
      200:
        description: OK, with version in body
        body:
          text/plain:
        headers:
          X-Okapi-Trace:
            description: Okapi trace and timing
      400:
        description: Bad Request
        body:
          text/plain:
      500:
        description: Server Error
        body:
          text/plain:

/_/invoke/tenant/{id}:
  description: Call module with Tenant ID in path. This
    service offers support for systems that need to "call-back" Okapi and
    don't allow setting the Tenant ID in the HTTP header.
  get:
    description: Invoke any service (the rest of the path, any method,
      any response).
    responses:
      200:
        description: OK
        body:
          text/plain:

#TODO implement single module health check