Another pickup point doc fix

Another pickup point doc fix

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.json
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.json
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.json
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.xml
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.xml
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.xml
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml

#%RAML 1.0
---
title: Pickup Point API
baseUri: https://api.bring.com/pickuppoint/api/pickuppoint

documentation:
- title: Introduction
  content: |
      The Pickup point API provides a list of locations for package pickup. Based on a specified postal code or a geographical location, the 10 nearest pickup points are returned, sorted by driving time by car(source: Google). In instances where google is unable to retrieve driving times from a location to a pickup point(e.g. location on mainland and pickup point on an island), these pickup points will be sorted by aerial distance and placed last in the list. Response is available as either XML or JSON.

      A pickup point is defined as any location delivering shipments on behalf of Bring and Posten, such as post offices, selected grocery stores, lockers, etc.

      It is important to note, there are two sets of addresses in the response, postbox(address, postalCode) and visiting address(visitingAddress,visitingPostalCode).Postbox address is required to get a package produced correctly, use this AS RECIPIENT address on label. Visiting address is more appropriate for user interface (Street address of the PIB).

      ### Filtering results

      In addition to postal code or location, one or more optional parameters can be added to the request, adding additional restrictions to the pickup points being returned. One such parameter is `searchForText=<texts>`, resulting in a response where all pickup points have at least a partial match with the search string given in `<texts>`. This can be the name of the pickup point, its address, city, county, municipality or location. Go to the reference table or see additional examples for more information.

      #### Distinct PickupPointType

      Norway :
        - Type 4  : Post i Butikk
        - Type 19 : Posten pakkeutlevering
        - Type 21 : Postkontor
        - Type 27 : Pakkeautomat
        - Type 32 : Postpunkt, egendrevet
        - Type 33 : Postpunkt
        - Type 37 : Pakkeboks

      Sweden :
        - Type 34 : Manned

      Denmark :
        - Type 85 : Manned
        - Type 86 : Locker

      Finland :
        - Type SmartPOST  : Finland Smart Post Pickup
        - Type Posti      : Finland Posti Pickup Point
        - Type Noutopiste : Finland Pickup Point
        - Type LOCKER     : Finland Locker Pickup Point

- title: Authentication
  content: |
      To make API requests, you will need an API key from Mybring. Steps for getting a key and description of headers can be found on the general API [Getting Started / Authentication](/api/#authentication) page.

/{countryCode}/postalCode/{postalCode}{mediaTypeExtension}:
  displayName: Pickup points for postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json, .xml to get application/xml or .html to get HTML.
  get:
    description: List pickup points for postal code
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default. Try this param to get more pickup points, if a desired pickup point is missing in the response.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street. Use this param to get more accurate result.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.Use this param to get more accurate result.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for NO/postalCode/1407
        body:
          application/json:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.json
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.json
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3 and postal code 2000.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.json
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.json
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.json
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.
          application/xml:
            examples:
              successful:
                displayName: Response for NO/postalCode/1407
                value: !include examples/by_postal_code.xml
              code_street:
                displayName: Postal code and street address
                value: !include examples/filter_address.xml
                description: |
                  Sometimes (especially in Denmark) it's a good idea to also specify the address when searching for pickup points, to get more accurate results.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/DK/postalCode/2000.json?street=Smallegade&streetNumber=3), we look for pickup points in Smallegade 3, 2000 Frederiksberg.
              specific_string:
                displayName: Pickup points containing a specific string
                value: !include examples/filter_search.xml
                description: |
                  If you want to return only the pickup points matching a specific string, you may use the `searchForText` query param. The given text can be the name of the pickup point, its address, city, county, municipality or location. Partial matches are also allowed.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?searchForText=KIWI), we look for pickup points near NO/1407 cotaining "Kiwi".
              specific_days:
                displayName: Pickup points open on specific days
                value: !include examples/filter_days.xml
                description: |
                  If you want to return only the pickup points open on specified days, you may use the `openingHoursSearchType=<day>` query param. `<day>` be:

                  - `ALL_WEEKDAYS` (default)
                  - `MONDAY`
                  - `TUESDAY`
                  - `WEDNESDAY`
                  - `THURSDAY`
                  - `FRIDAY`
                  - `SATURDAY`
                  - `SUNDAY`

                  If you want you can also add `openOnOrBefore` and / or `openOnOrAfter`, to limit the search even more.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openingHoursSearchType=SUNDAY), we look for pickup points near NO/1407 that are open Sundays.
              specific_hours:
                displayName: Pickup points open at specific hours
                value: !include examples/filter_hours.xml
                description: |
                  If you want to return only the pickup points open on specific hours, you may use the `openOnOrBefore=<time>` and/or `openOnOrAfter=<time>` query params.

                  The format of `<time>` is `HHmm`.

                  In [this example](https://api.bring.com/pickuppoint/api/pickuppoint/NO/postalCode/1407.json?openOnOrBefore=0800), we look for pickup points near NO/1407 open on or before 08:00.

/{countryCode}/location/{latitude},{longitude}{mediaTypeExtension}:
  displayName: Pickup points for location
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", "DK", "SE", "FI" ]
    latitude:
      displayName: Latitude
      description: Geographic coordinate specifying the north-south position.
      type: string
    longitude:
      displayName: Longitude
      description: Geographic coordinate specifying the east-west position.
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List pickup points closest to location
    queryParameters:
      searchForText:
        displayName: Text filter
        type: string
      openingHoursSearchType:
        displayName: Filter using opening hours
        enum: [ ALL_WEEKDAYS, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY ]
      openOnOrBefore:
        description: Format `HHmm`. Return only pickup points that are open on or before the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      openOnOrAfter:
        description: Format `HHmm`. Return only pickup points that are open on or after the specified time.
        type: string
        pattern: ^([01][0-9]|2[0-3])[0-5][0-9]$
      pickupPointType:
        displayName: Pickup-point type
        description: Currently available for Swedish, Finnish and Danish pickup point request only.
        enum: [ manned, locker ]
      numberOfResponses:
        description: Return the specified number of pickup points instead of the default.
        type: integer
        default: 10
      street:
        description: Searches for the nearest pickup points to the given street.
        type: string
      streetNumber:
        description: Searches for the nearest pickup points to the given street number.
        type: string
      callback:
        description: JSONP callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for location/60.395226,5.321725
        body:
          application/json:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.json
          application/xml:
            examples:
              successful:
                displayName: Response for location/60.395226,5.321725
                value: !include examples/by_coordinates.xml

/{countryCode}/id/{id}{mediaTypeExtension}:
  displayName: A specific pickup point
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: Look up a specific pickup point
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string
    responses:
      200:
        displayName: Example response for id/121110
        body:
          application/json:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.json
          application/xml:
            examples:
              successful:
                displayName: Response for id/121110
                value: !include examples/by_id.xml

/{countryCode}/all{mediaTypeExtension}:
  displayName: All pickup points in a country
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO", DK, SE, FI ]
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: All pickup points in a country
    queryParameters:
      callback:
        displayName: JSONP support
        description: Callback function name.
        type: string
      requestCountryCode:
        description: Country code of the requester. Only applicable for Norwegian pickup points.
        type: string

/{countryCode}/postalCode/{postalCode}/default/{mediaTypeExtension}:
  displayName: Default pickup point(s) for a postal code
  uriParameters:
    countryCode:
      displayName: Country
      enum: [ "NO" ]
    postalCode:
      displayName: Postal code
      type: string
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to get application/json or .xml to get application/xml.
  get:
    description: List default pickup point(s) for a postal code
    responses:
      200:
        displayName: Example response for postal code 1481
        body:
          application/json:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            examples:
              successful:
                displayName: Response for postal code 1481
                value: !include examples/default_pickup_point_by_postal_code.xml


Use a number instead of a string so JSON Test Data doesn't generate something random

#%RAML 0.8
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

/authors:
  get:
    description: Retrieve a list of authors
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "schema for a list of authors",
                "type": "object",
                "properties": {
                  "data": {
                    "type": "number"
                  }
                }
              }

#%RAML 0.8
---
title: e-BookMobile API
baseUri: http://api.e-bookmobile.com/{version}
version: v1

/authors:
  get:
    description: Retrieve a list of authors
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "description": "schema for a list of authors",
                "type": "object",
                "properties": {
                  "data": {
                    "type": "string"
                  }
                }
              }


[#8044] fix RAML syntax

[#8044] fix RAML syntax

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

        /{ticketNumber}:
          type: {
            generic: {
              example: !include examples/ticket.json,
              schema: !include schemas/ticket.json
            }
          }
          displayName: Ticket Number
          uriParameters:
            ticketNumber:
              example: 1
              description: |
                Get a details of a ticket.

          /save:
            description: |
              updates an existing ticket
              parameters are the same as /rest/p/project_name/mount_point/new

            post:
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    access_token:
                      description: "The access token provided by the authentication application"
                      required: true
                      type: string
                    ticket_form.summary:
                      description: Ticket title
                      type: string
                      required: false
                    ticket_form.description:
                      description: ticket description
                      type: string
                      required: false
                    ticket_form.assigned_to::
                      type: string
                      required: false
                      description: username of ticket assignee
                    ticket_form.labels:
                      type: string
                      required: false
                      description:  comma-separated list of ticket labels
                    ticket_form.attachment:
                      type: file
                      description:  (optional) attachment
                      required: false
                    ticket_form.custom field name:
                      description:  custom field value
                      type: string
                      required: false

        /search:
          type: {
            searchableCollection: {
              queryParamName: q,
              queryParamExample: 'example',
              queryRequired: true,
              schema: !include schemas/searchedTickets.json,
              example: !include examples/searchedTickets.json
            }
          }
          is: [ pageable]

        /new:
          description: |
            Creates a new ticket.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  access_token:
                    description: "The access token provided by the authentication application"
                    required: true
                    type: string
                  ticket_form.summary:
                    description: Ticket title
                    type: string
                    required: false
                  ticket_form.description:
                    description: ticket description
                    type: string
                    required: false
                  ticket_form.assigned_to::
                    type: string
                    required: false
                    description: username of ticket assignee
                  ticket_form.labels:
                    type: string
                    required: false
                    description:  comma-separated list of ticket labels
                  ticket_form.attachment:
                    type: file
                    description:  (optional) attachment
                    required: false
                  ticket_form.custom field name:
                    description:  custom field value
                    type: string
                    required: false

        /_discuss/thread/{threadId}:
          uriParameters:
           threadId:
             displayName: Thread ID
             type: string
             example: f78b98a0

          get:
            description: |
              returns summary information about a thread, including the posts in a thread
            is: [ bearerAuth, pageable ]
          /{slug}:
            uriParameters:
             slug:
               displayName: Slug
               type: string
               example: 9133
            get:
              description: |
                returns detailed information about a post
              is: [ bearerAuth ]
            /reply:
              description: |
                create a threaded reply to the given post
              post:
                is: [ bearerAuth ]
                body:
                  application/x-www-form-urlencoded:
                    formParameters:
                      text:
                        description: the text of the reply
                        example: |
                          I *agree* with you.
                        required: true
                        type: string
          /new:
            description: |
              create a post in the given thread
            post:
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    text:
                      description: The text of the new post
                      example: |
                        This is a new post!
                      required: true
                      type: string

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read, create, delete, update, save_searches]

      /{discussion}:
        description: |
          Represents the **Discussion Tool**.
        type: {
          generic: {
            schema: !include schemas/discussion.json,
            example: !include examples/discussion.json
            }
          }

        displayName: Discussion
        uriParameters:
         discussion:
           displayName: Discussion Tool Name
           type: string
           example: "discussion"
        get:
          description: |
            Returns a list of forums, including name, description, num_topics, and last_post details
          is: [pageable]

        /{forum}:
          description: |
            Represents a forum within a Discussion tool.
          type: {
            generic: {
              example: !include examples/forum.json,
              schema: !include schemas/forum.json
            }
          }
          displayName: forum
          uriParameters:
           forum:
             displayName: Forum Name
             type: string
             example: general

          get:
            is: [pageable]
            description: |
              returns a limited list of topics in the forum, with fields for subject, num_replies, API URL, and last_post
              To view more than 100 threads, or 100 posts in a thread, use the pagination support of the API by adding ?page=1 etc. to the URL.

          /thread/{thread}:
            description: |
              Represents a thread of posts.
            get:
              is: [pageable, bearerAuth]
              description: |
                returns a list of posts in the thread, with fields for author, text, and timestamp. Nested posts (i.e. a reply to a post) can be determined by the slug structure. For example, "slug": "0a0b/9f00" is a reply to the post with "slug": "0a0b"

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read]

      /{blog}:
        type: {
          generic: {
            example: !include examples/blog.json,
            schema: !include schemas/blog.json
          }
        }
        description: |
          Represents the **Blog tool**

        displayName: Blog
        uriParameters:
         blog:
           displayName: Blog Name
           type: string
           example: blog

        get:
          description: |
            Returns a list of posts, including title and API url.
        post:
          description: |
            Creates a new blog post.
          is: [ bearerAuth ]
          body:
            application/x-www-form-urlencoded:
              formParameters:
                title:
                  description: |
                    The title of the post.
                  type: string
                  example: New API docs released!
                text:
                  description: |
                    The text of the post.
                  type: string
                  example: Lots of text here describing apis!\nThat is all.
                labels:
                  description: |
                    Labels of the post -- comma seperated strings
                  type: string
                  example: api,development
                state:
                  description: |
                    Draft or published.
                  enum: [draft, published]
                  type: string
                  example: published

        /{year}/{month}/{title}:
            description: Represents a blog post entry.
            type: {
              generic: {
                example: !include examples/blogPost.json,
                schema: !include schemas/blogPost.json
              }
            }
            displayName: Blog Post
            uriParameters:
             year:
               displayName: Year
               type: number
               example: 2015
             month:
               displayName: Month
               type: string
               example: 04
             title:
               displayName: Title
               type: string
               example: project-insights

            post:
              description: |
                Updates an existing blog post.
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    title:
                      description: |
                        The title of the post.
                      type: string
                    text:
                      description: |
                        The text of the post.
                      type: string
                    labels:
                      description: |
                        Labels of the post -- comma seperated strings
                      type: string
                    state:
                      description: |
                        Draft or published.
                      enum: [draft, published]
                      type: string

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read, write]

      /{link}:
        description: |
          Represents the External Link tool.
        type: {
          generic: {
            example: !include examples/link.json,
            schema: !include schemas/link.json
          }
        }

        get:
          description: |
            Returns the existing url.

        post:
          description: |
            Updates the url. *authentication required*.
          is: [ bearerAuth ]
          body:
            application/x-www-form-urlencoded:
              formParameters:
                url:
                  description: |
                    The url you would like to update to.
                  type: string
                  example: http://google.com

      /admin:
        description: |
          Endpoints for **project exporting** and managing **webhooks**

        /export:
          description: |
            Generates a full bulk export of your tool(s) in the same format as the API for individual access. Authentication required. Here is an [example shell](https://forge-allura.apache.org/p/allura/git/ci/master/tree/scripts/project_export) script using these APIs, suitable to run as a cron job.
          post:
            description: |
              Submits an export job

              **400 Bad Request:** tools parameter not provided or is invalid
              **503 Service Unavailable:** an export job is already running
              **200 OK:** job submitted. Body will be: *{"status": "in progress", "filename": FILENAME}*
            is: [ bearerAuth ]
        /export_status:
          description: |
            Check status of a bulk export job
          get:
            description: |
              Returns status: busy or ready
            is: [ bearerAuth ]
        /{tool}/webhooks:
            type: {
              typedCollection: {
              example: !include examples/webhooks.json,
              schema: !include schemas/webhooks.json
              }
            }
            description: |
              This is to manage webhooks programatically. See the [Webhook docs](https://forge-allura.apache.org/p/allura/wiki/Webhooks/) for more information.

              The webhook payloads and signature verification method are documented at https://forge-allura.apache.org/p/allura/wiki/Webhooks/
            get:
              description: |
                Returns the list of webhooks

            /{type}:
              uriParameters:
                type:
                  example: repo-push
                  enum: [repo-push]
                  description: |
                    Allura supports one type of webhook for the moment - repo-push, triggered when a repository receives new commits. It is supported for Git, Mercurial and SVN repositories.
              post:
                description: |
                  Create a new webhook.
                is: [ bearerAuth ]
                body:
                  application/x-www-form-urlencoded:
                    formParameters:
                      url:
                        description: |
                          The url to call when the the webhook is triggered.
                        required: true
                        type: string
              /{id}:
                type: {
                  generic: {
                    example: !include examples/webhook.json,
                    schema: !include schemas/webhook.json
                  }
                }
                uriParameters:
                  id:
                    type: string
                    description: |
                      Unique identifier for a webhook.
                get:
                  description: |
                    View a webhook
                post:
                  description: |
                    Update an existing webhook
                  is: [ bearerAuth ]
                  body:
                    application/x-www-form-urlencoded:
                      formParameters:
                        url:
                          description: |
                            The url to call when the the webhook is triggered.
                          required: true
                          type: string
                        secret:
                          description: |
                            Optionally supply your own secret.

                            Note: DO NOT ever expose your secret!
                          required: false
                          type: string
                delete:
                  is: [ bearerAuth ]
                  description: |
                    Delete an existing webhook
        /install_tool:
          description: |
            Adds a new tool to the project. *Authentication Required*.

            returns dict with two fields:
            success: False if error is occurred, otherwise True
            info: success or error message
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  tool:
                    description: Tool name that you want to install.
                    example: tickets
                    enum: [tickets, link, git, svn, mercurial, blog, discussion, subproject, wiki]
                    required: true
                    type: string
                  mount_point:
                    description: |
                      The section of the url relative to your project. For example: /p/your_project/{mount_point}
                    example: git
                    type: string
                    required: true
                  mount_label:
                    description: |
                      How your tool will be displayed in your project (like a "nice name" for the tool).
                    example: Git
                    type: string
                    required: true
                  order:
                    type: string
                    enum: [first, last, alpha_tool]
                    required: false
                    description: |
                      "first", "last", or "alpha_tool" for position with respect to existing tools (or existing tools of the same type for "alpha_tool")
        /mount_order:
          description: |
            Save tool/subproject order for multiple tools at once.  *Authentication Required*.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  1:
                    description: Mount point name for the first position.
                    example: tickets
                    type: string
                  2:
                    description: Mount point name for the second position.
                    example: our-news
                    type: string
                  3:
                    description: Mount point name for the third position.
                    example: documentation
                    type: string
                  4...:
                    description: Etc.
        /configure_tool_grouping:
          description: |
            Set the nav bar grouping threshold. *Authentication Required*.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  grouping_threshold:
                    description: Value for the grouping threshold.
                    example: 1
                    type: number
        /installable_tools:
          description: |
            List of installable tools and their default options.  *Authentication Required*.
          get:
            is: [ bearerAuth ]
        /admin_options:
          description: |
            List of links to admin pages or modal content, for a specific tool. *Authentication Required*.
          get:
            is: [ bearerAuth ]
            queryParameters:
              mount_point:
                type: string
                description: |
                  The mount point to specify which tool.

/u/{username}:
    description: |
      Represents a user.  This returns a project-like response, since users all automatically have a personal project.  Like a project, any tool within a user-project is available through the API as well at /u/{username}/{tool}

      Most often you'll use the /profile suffix to return user data.
    type: {
      generic: {
        example: !include examples/user.json,
        schema: !include schemas/user.json
      }
    }
    /profile:
      description: |
        A user profile
      type: {
        generic: {
          example: !include examples/userProfile.json,
          schema: !include schemas/userProfile.json
        }
      }

/notification:
  description: |
    Get current Site Notification
  get:
    queryParameters:
      cookie:
        description: site-notification cookie value
        example: "56a111736c4ff90011b9f932-1-False"
      url:
        description: page where notification will be shown
        example: "/p/test-project"
      tool_name:
        description: tool's name for current page
        example: "Git"

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

        /{ticketNumber}:
          type: {
            generic: {
              example: !include examples/ticket.json,
              schema: !include schemas/ticket.json
            }
          }
          displayName: Ticket Number
          uriParameters:
            ticketNumber:
              example: 1
              description: |
                Get a details of a ticket.

          /save:
            description: |
              updates an existing ticket
              parameters are the same as /rest/p/project_name/mount_point/new

            post:
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    access_token:
                      description: "The access token provided by the authentication application"
                      required: true
                      type: string
                    ticket_form.summary:
                      description: Ticket title
                      type: string
                      required: false
                    ticket_form.description:
                      description: ticket description
                      type: string
                      required: false
                    ticket_form.assigned_to::
                      type: string
                      required: false
                      description: username of ticket assignee
                    ticket_form.labels:
                      type: string
                      required: false
                      description:  comma-separated list of ticket labels
                    ticket_form.attachment:
                      type: file
                      description:  (optional) attachment
                      required: false
                    ticket_form.custom field name:
                      description:  custom field value
                      type: string
                      required: false

        /search:
          type: {
            searchableCollection: {
              queryParamName: q,
              queryParamExample: 'example',
              queryRequired: true,
              schema: !include schemas/searchedTickets.json,
              example: !include examples/searchedTickets.json
            }
          }
          is: [ pageable]

        /new:
          description: |
            Creates a new ticket.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  access_token:
                    description: "The access token provided by the authentication application"
                    required: true
                    type: string
                  ticket_form.summary:
                    description: Ticket title
                    type: string
                    required: false
                  ticket_form.description:
                    description: ticket description
                    type: string
                    required: false
                  ticket_form.assigned_to::
                    type: string
                    required: false
                    description: username of ticket assignee
                  ticket_form.labels:
                    type: string
                    required: false
                    description:  comma-separated list of ticket labels
                  ticket_form.attachment:
                    type: file
                    description:  (optional) attachment
                    required: false
                  ticket_form.custom field name:
                    description:  custom field value
                    type: string
                    required: false

        /_discuss/thread/{threadId}:
          uriParameters:
           threadId:
             displayName: Thread ID
             type: string
             example: f78b98a0

          get:
            description: |
              returns summary information about a thread, including the posts in a thread
            is: [ bearerAuth, pageable ]
          /{slug}:
            uriParameters:
             slug:
               displayName: Slug
               type: string
               example: 9133
            get:
              description: |
                returns detailed information about a post
              is: [ bearerAuth ]
            /reply:
              description: |
                create a threaded reply to the given post
              post:
                is: [ bearerAuth ]
                body:
                  application/x-www-form-urlencoded:
                    formParameters:
                      text:
                        description: the text of the reply
                        example: |
                          I *agree* with you.
                        required: true
                        type: string
          /new:
            description: |
              create a post in the given thread
            post:
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    text:
                      description: The text of the new post
                      example: |
                        This is a new post!
                      required: true
                      type: string

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read, create, delete, update, save_searches]

      /{discussion}:
        description: |
          Represents the **Discussion Tool**.
        type: {
          generic: {
            schema: !include schemas/discussion.json,
            example: !include examples/discussion.json
            }
          }

        displayName: Discussion
        uriParameters:
         discussion:
           displayName: Discussion Tool Name
           type: string
           example: "discussion"
        get:
          description: |
            Returns a list of forums, including name, description, num_topics, and last_post details
          is: [pageable]

        /{forum}:
          description: |
            Represents a forum within a Discussion tool.
          type: {
            generic: {
              example: !include examples/forum.json,
              schema: !include schemas/forum.json
            }
          }
          displayName: forum
          uriParameters:
           forum:
             displayName: Forum Name
             type: string
             example: general

          get:
            is: [pageable]
            description: |
              returns a limited list of topics in the forum, with fields for subject, num_replies, API URL, and last_post
              To view more than 100 threads, or 100 posts in a thread, use the pagination support of the API by adding ?page=1 etc. to the URL.

          /thread/{thread}:
            description: |
              Represents a thread of posts.
            get:
              is: [pageable, bearerAuth]
              description: |
                returns a list of posts in the thread, with fields for author, text, and timestamp. Nested posts (i.e. a reply to a post) can be determined by the slug structure. For example, "slug": "0a0b/9f00" is a reply to the post with "slug": "0a0b"

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read]

      /{blog}:
        type: {
          generic: {
            example: !include examples/blog.json,
            schema: !include schemas/blog.json
          }
        }
        description: |
          Represents the **Blog tool**

        displayName: Blog
        uriParameters:
         blog:
           displayName: Blog Name
           type: string
           example: blog

        get:
          description: |
            Returns a list of posts, including title and API url.
        post:
          description: |
            Creates a new blog post.
          is: [ bearerAuth ]
          body:
            application/x-www-form-urlencoded:
              formParameters:
                title:
                  description: |
                    The title of the post.
                  type: string
                  example: New API docs released!
                text:
                  description: |
                    The text of the post.
                  type: string
                  example: Lots of text here describing apis!\nThat is all.
                labels:
                  description: |
                    Labels of the post -- comma seperated strings
                  type: string
                  example: api,development
                state:
                  description: |
                    Draft or published.
                  enum: [draft, published]
                  type: string
                  example: published

        /{year}/{month}/{title}:
            description: Represents a blog post entry.
            type: {
              generic: {
                example: !include examples/blogPost.json,
                schema: !include schemas/blogPost.json
              }
            }
            displayName: Blog Post
            uriParameters:
             year:
               displayName: Year
               type: number
               example: 2015
             month:
               displayName: Month
               type: string
               example: 04
             title:
               displayName: Title
               type: string
               example: project-insights

            post:
              description: |
                Updates an existing blog post.
              is: [ bearerAuth ]
              body:
                application/x-www-form-urlencoded:
                  formParameters:
                    title:
                      description: |
                        The title of the post.
                      type: string
                    text:
                      description: |
                        The text of the post.
                      type: string
                    labels:
                      description: |
                        Labels of the post -- comma seperated strings
                      type: string
                    state:
                      description: |
                        Draft or published.
                      enum: [draft, published]
                      type: string

        /has_access:
          type: permission
          get:
            queryParameters:
              perm:
                displayName: Permission
                required: true
                type: string
                example: post
                default: read
                enum: [admin, configure, moderate, post, unmoderated_post, read, write]

      /{link}:
        description: |
          Represents the External Link tool.
        type: {
          generic: {
            example: !include examples/link.json,
            schema: !include schemas/link.json
          }
        }

        get:
          description: |
            Returns the existing url.

        post:
          description: |
            Updates the url. *authentication required*.
          is: [ bearerAuth ]
          body:
            application/x-www-form-urlencoded:
              formParameters:
                url:
                  description: |
                    The url you would like to update to.
                  type: string
                  example: http://google.com

      /admin:
        description: |
          Endpoints for **project exporting** and managing **webhooks**

        /export:
          description: |
            Generates a full bulk export of your tool(s) in the same format as the API for individual access. Authentication required. Here is an [example shell](https://forge-allura.apache.org/p/allura/git/ci/master/tree/scripts/project_export) script using these APIs, suitable to run as a cron job.
          post:
            description: |
              Submits an export job

              **400 Bad Request:** tools parameter not provided or is invalid
              **503 Service Unavailable:** an export job is already running
              **200 OK:** job submitted. Body will be: *{"status": "in progress", "filename": FILENAME}*
            is: [ bearerAuth ]
        /export_status:
          description: |
            Check status of a bulk export job
          get:
            description: |
              Returns status: busy or ready
            is: [ bearerAuth ]
        /{tool}/webhooks:
            type: {
              typedCollection: {
              example: !include examples/webhooks.json,
              schema: !include schemas/webhooks.json
              }
            }
            description: |
              This is to manage webhooks programatically. See the [Webhook docs](https://forge-allura.apache.org/p/allura/wiki/Webhooks/) for more information.

              The webhook payloads and signature verification method are documented at https://forge-allura.apache.org/p/allura/wiki/Webhooks/
            get:
              description: |
                Returns the list of webhooks

            /{type}:
              uriParameters:
                type:
                  example: repo-push
                  enum: [repo-push]
                  description: |
                    Allura supports one type of webhook for the moment - repo-push, triggered when a repository receives new commits. It is supported for Git, Mercurial and SVN repositories.
              post:
                description: |
                  Create a new webhook.
                is: [ bearerAuth ]
                body:
                  application/x-www-form-urlencoded:
                    formParameters:
                      url:
                        description: |
                          The url to call when the the webhook is triggered.
                        required: true
                        type: string
              /{id}:
                type: {
                  generic: {
                    example: !include examples/webhook.json,
                    schema: !include schemas/webhook.json
                  }
                }
                uriParameters:
                  id:
                    type: string
                    description: |
                      Unique identifier for a webhook.
                get:
                  description: |
                    View a webhook
                post:
                  description: |
                    Update an existing webhook
                  is: [ bearerAuth ]
                  body:
                    application/x-www-form-urlencoded:
                      formParameters:
                        url:
                          description: |
                            The url to call when the the webhook is triggered.
                          required: true
                          type: string
                        secret:
                          description: |
                            Optionally supply your own secret.

                            Note: DO NOT ever expose your secret!
                          required: false
                          type: string
                delete:
                  is: [ bearerAuth ]
                  description: |
                    Delete an existing webhook
        /install_tool:
          description: |
            Adds a new tool to the project. *Authentication Required*.

            returns dict with two fields:
            success: False if error is occurred, otherwise True
            info: success or error message
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  tool:
                    description: Tool name that you want to install.
                    example: tickets
                    enum: [tickets, link, git, svn, mercurial, blog, discussion, subproject, wiki]
                    required: true
                    type: string
                  mount_point:
                    description: |
                      The section of the url relative to your project. For example: /p/your_project/{mount_point}
                    example: git
                    type: string
                    required: true
                  mount_label:
                    description: |
                      How your tool will be displayed in your project (like a "nice name" for the tool).
                    example: Git
                    type: string
                    required: true
                  order:
                    type: string
                    enum: [first, last, alpha_tool]
                    required: false
                    description: |
                      "first", "last", or "alpha_tool" for position with respect to existing tools (or existing tools of the same type for "alpha_tool")
        /mount_order:
          description: |
            Save tool/subproject order for multiple tools at once.  *Authentication Required*.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  1:
                    description: Mount point name for the first position.
                    example: tickets
                    type: string
                  2:
                    description: Mount point name for the second position.
                    example: our-news
                    type: string
                  3:
                    description: Mount point name for the third position.
                    example: documentation
                    type: string
                  4...:
                    description: Etc.
        /configure_tool_grouping:
          description: |
            Set the nav bar grouping threshold. *Authentication Required*.
          post:
            is: [ bearerAuth ]
            body:
              application/x-www-form-urlencoded:
                formParameters:
                  grouping_threshold:
                    description: Value for the grouping threshold.
                    example: 1
                    type: number
        /installable_tools:
          description: |
            List of installable tools and their default options.  *Authentication Required*.
          get:
            is: [ bearerAuth ]
        /admin_options:
          description: |
            List of links to admin pages or modal content, for a specific tool. *Authentication Required*.
          get:
            is: [ bearerAuth ]
            queryParameters:
              mount_point:
                type: string
                description: |
                  The mount point to specify which tool.

/u/{username}:
    description: |
      Represents a user.  This returns a project-like response, since users all automatically have a personal project.  Like a project, any tool within a user-project is available through the API as well at /u/{username}/{tool}

      Most often you'll use the /profile suffix to return user data.
    type: {
      generic: {
        example: !include examples/user.json,
        schema: !include schemas/user.json
      }
    }
    /profile:
      description: |
        A user profile
      type: {
        generic: {
          example: !include examples/userProfile.json,
          schema: !include schemas/userProfile.json
        }
      }

/notification:
  description: |
    Get current Site Notification
  uriParameters:
    cookie:
      description: site-notification cookie value
      example: "56a111736c4ff90011b9f932-1-False"
    url:
      description: page where must be shown notification
      example: "/p/test-project"
    tool_name:
      description: tool's name which used on page
      exaple: "Git"