Adjust text related to authentication

Adjust text related to authentication

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

documentation:
- title: Introduction
  content: |

        The Pickup Point API became authenticated from 01.11.2020

            We have now started to limit the data in the responses for unauthenticated requests:

             - From 01.11.2020, coordinates and map links have been removed from all responses.
             - From 09.11.2020, only 1 pickup point will be returned in the responses for the postal code and location endpoints

            We recommend making the adjustment as soon as possible to avoid any problems with your integration setup during peak.

      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.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the service list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact us](mailto:developer@bring.com) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

      #### 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: |
      The Pickup Point API requires authentication. 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:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        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.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        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".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        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.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        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.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{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:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !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:
            example: !include examples/by_id.json
          application/xml:
            example: !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:
            example: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            example: !include examples/default_pickup_point_by_postal_code.xml

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

documentation:
- title: Introduction
  content: |

        The Pickup Point API becomes authenticated from 01.11.2020

            Our customers are increasingly demanding new functionality and solutions that are easy to use. To meet these expectations, we must know which customers and partners are using our APIs and how they are using them.

            To further develop the value proposition of our Pickup Point API, the solution becomes authenticated from 01.11.2020.

            We recommend making the adjustment already now, well in advance of summer vacations and peak season.

      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.

      ### Rate limiting

      The Pickup point API has a rate limit, primarily considered on a per-user basis. Currently it limits API users to no more than 60 requests within a minute from a single IP address.

      Once you go over the rate limit, you will receive a response with an HTTP response code of 429 (Too Many Requests). The body of the response will consist of the following fields:

      - `code`: `429`
      - `error_message`: `The maximum number of requests per minute has been exceeded.`

      As an additional note, While accessing the Pickup point API together with Shipping Guide API, the service list should be displayed even in the case that the request has been rate limited by the Pickup point API.

      #### High-volume users

      If you're a high-volume user of the Pickup Point API, please [contact us](mailto:developer@bring.com) to discuss your options.

      When contacting Bring support include a description of how you are using the Pickup Point API, also an estimate of current request volumes.

      #### 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: |
      The Pickup Point API requires authentication. 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:
            example: !include examples/by_postal_code.json
          application/xml:
            example: !include examples/by_postal_code.xml
      250:
        displayName: Using postal code and street address
        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.
        body:
          application/json:
            example: !include examples/filter_address.json
          application/xml:
            example: !include examples/filter_address.xml
      251:
        displayName: Find pickup points containing a specific string
        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".
        body:
          application/json:
            example: !include examples/filter_search.json
          application/xml:
            example: !include examples/filter_search.xml
      252:
        displayName: Find pickup points open on specific days
        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.
        body:
          application/json:
            example: !include examples/filter_days.json
          application/xml:
            example: !include examples/filter_days.xml
      253:
        displayName: Find pickup points open at specific hours
        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.
        body:
          application/json:
            example: !include examples/filter_hours.json
          application/xml:
            example: !include examples/filter_hours.xml

/{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:
            example: !include examples/by_coordinates.json
          application/xml:
            example: !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:
            example: !include examples/by_id.json
          application/xml:
            example: !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:
            example: !include examples/default_pickup_point_by_postal_code.json
          application/xml:
            example: !include examples/default_pickup_point_by_postal_code.xml


added /bookId PUT resource

added /bookId PUT resource

#%RAML 0.8
title: Test API
version: v1
baseUri: http://{apiUri}/api/{version}
mediaType: application/json
protocols: [ HTTP ]
schemas:
  - BookRecord: !include schemas/BookRecord.json
  - CommonResponseObject: |
      {
        "type": "object",
        "$schema": "http://json-schema.org/draft-03/schema",
        "id": "http://jsonschema.net",
        "required": true,
        "properties": {
          "success": {
            "type": "boolean",
            "required": true
          },
          "message": {
            "type": "string",
            "required": false
          }
        }
      }
securitySchemes:
  - basic:
      type: Basic Authentication
traits:
  - sorted:
      description: A sorted collection resource
      queryParameters:
        sort_by:
          displayName: Sort by property
          description: The name of the property to sort by
          type: string
          example: "title"
          default: "id"
        sort_reversed:
          displayName: Reversed sort order
          description: Reverse the sort order
          type: boolean
          example: true
          default: false
  - paged:
      description: A paged collection resource
      queryParameters:
        limit:
          displayName: Limit
          description: The maximum number of items to return
          type: integer
          example: 10
          minimum: 0
          default: 20
          maximum: 50
        offset:
          displayName: Offset
          description: The index of the first item to return
          type: integer
          example: 5
          default: 0
/books:
  securedBy: [basic]
  displayName: Books Service
  description: Get your books here!
  post:
    description: Creates a new book record
    body:
      application/json:
        schema: BookRecord
    responses:
      201:
        description: A book was successfully created
        body:
          application/json:
            schema: CommonResponseObject
            example: |
              {
                "success": true,
                "message": "Book created"
              }

  get:
    is: [paged, sorted]
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "type": "array",
                "items": {
                  "$ref": "BookRecord"
                }
              }
            example: |
              [{
                "id": 100,
                "title": "War and piece",
                "author": "Leo Tolstoi",
                "isbn": "12345"
              }, {
                "id": 200,
                "title": "Catcher in the rye",
                "author": "J. D. Salinger",
                "isbn": "54321"
              }]
  /{bookId}:
    displayName: Get or update a book by id
    uriParameters:
      bookId:
        displayName: Book id
        type: integer
    get:
        description: Get a book by its ID
        responses:
          200:
            body:
              application/json:
                schema: BookRecord
                example: |
                  {
                    "id": 200,
                    "title": "Catcher in the rye",
                    "author": "J. D. Salinger",
                    "isbn": "54321"
                  }
          404:
            body:
              application/json:
                schema: CommonResponseObject
                example: |
                  {
                    "success": false,
                    "message": "Book not found"
                  }
    put:
      description: Update an existing book given book id
      body:
        application/json:
          schema: BookRecord
          example: |
            {
              "id": 200,
              "title": "Catcher in the rye",
              "author": "J. D. Salinger",
              "isbn": "54321"
            }
      responses:
        200:
          description: A book was successfully updated
          body:
            application/json:
              schema: CommonResponseObject
              example: |
                {
                  "success": true,
                  "message": "Book updated"
                }
        404:
          description: Book not found
          body:
            application/json:
              schema: CommonResponseObject
              example: |
                {
                  "success": false,
                  "message": "Book not found"
                }

#%RAML 0.8
title: Test API
version: v1
baseUri: http://{apiUri}/api/{version}
mediaType: application/json
protocols: [ HTTP ]
schemas:
  - BookRecord: !include schemas/BookRecord.json
  - CommonResponseObject: |
      {
        "type": "object",
        "$schema": "http://json-schema.org/draft-03/schema",
        "id": "http://jsonschema.net",
        "required": true,
        "properties": {
          "success": {
            "type": "boolean",
            "required": true
          },
          "message": {
            "type": "string",
            "required": false
          }
        }
      }
securitySchemes:
  - basic:
      type: Basic Authentication
traits:
  - sorted:
      description: A sorted collection resource
      queryParameters:
        sort_by:
          displayName: Sort by property
          description: The name of the property to sort by
          type: string
          example: "title"
          default: "id"
        sort_reversed:
          displayName: Reversed sort order
          description: Reverse the sort order
          type: boolean
          example: true
          default: false
  - paged:
      description: A paged collection resource
      queryParameters:
        limit:
          displayName: Limit
          description: The maximum number of items to return
          type: integer
          example: 10
          minimum: 0
          default: 20
          maximum: 50
        offset:
          displayName: Offset
          description: The index of the first item to return
          type: integer
          example: 5
          default: 0
/books:
  securedBy: [basic]
  displayName: Books Service
  description: Get your books here!
  post:
    description: Creates a new book record
    body:
      application/json:
        schema: BookRecord
    responses:
      201:
        description: A book was successfully created
        body:
          application/json:
            schema: CommonResponseObject
            example: |
              {
                "success": true,
                "message": "Book created"
              }

  get:
    is: [paged, sorted]
    responses:
      200:
        body:
          application/json:
            schema: |
              {
                "$schema": "http://json-schema.org/draft-03/schema",
                "type": "array",
                "items": {
                  "$ref": "BookRecord"
                }
              }
            example: |
              [{
                "id": 100,
                "title": "War and piece",
                "author": "Leo Tolstoi",
                "isbn": "12345"
              }, {
                "id": 200,
                "title": "Catcher in the rye",
                "author": "J. D. Salinger",
                "isbn": "54321"
              }]
  /{bookId}:
    displayName: Get a book by id
    uriParameters:
      bookId:
        displayName: Book id
        type: integer
    get:
        responses:
          200:
            body:
              application/json:
                schema: BookRecord
                example: |
                  {
                    "id": 200,
                    "title": "Catcher in the rye",
                    "author": "J. D. Salinger",
                    "isbn": "54321"
                  }
          404:
            body:
              application/json:
                schema: CommonResponseObject
                example: |
                  {
                    "success": false,
                    "message": "Book not found"
                  }


improved title

improved title

#%RAML 0.8
---
title: Example HTTP JSON API
baseUri: http://localhost:8080/{version}
version: v1

/articles:
 description: Collection of tech articles
 get:
  queryParameters:
   author:
    displayName: Author
    type: string
    description: The author's name of the articles to search.
    example: Kai
    required: false
  responses:
   200:
    body:
     application/json:
      schema: |
       {
       	"type":"array",
       	"items": [
         {
          "type":"object",
          "properties":
           {
            "id": { "type": "integer" },
            "content": { "type": "string" }
           }
         }
        ]
       }
 /{articleId}:
  get:
   responses:
    200:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 200
        }
  post:
   responses:
    201:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 201
        }

#%RAML 0.8
---
title: Java Magazin API
baseUri: http://localhost:8080/{version}
version: v1

/articles:
 description: Collection of Java articles
 get:
  queryParameters:
   author:
    displayName: Author
    type: string
    description: The author's name of the articles to search.
    example: Kai
    required: false
  responses:
   200:
    body:
     application/json:
      schema: |
       {
       	"type":"array",
       	"items": [
         {
          "type":"object",
          "properties":
           {
            "id": { "type": "integer" },
            "content": { "type": "string" }
           }
         }
        ]
       }
 /{articleId}:
  get:
   responses:
    200:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 200
        }
  post:
   responses:
    201:
     body:
      application/json:
       example: |
        {
         "data":
         {
          "id": "2",
          "content": "abc"
         },
         "success": true,
         "status": 201
        }


[raml] Remove redundant type declaration

Since all our api endpoints return application/json we declare it just
once at the top (and it's already declared as a default)

#%RAML 0.8

title: "Portal API - DRAFT!!!"
version: v1
mediaType: application/json

/api:
  get:
    description: "List of available versions"
    responses:
      200:
        body:
          schema: !include schemas/200.json
          example: !include response_examples/200/versions.json

/api/{version}:
  /regions:
    get:
      description: List of regions
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/regions.json

  /regions/detailed:
    get:
      description: "Detailed information about regions."
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/regions_detailed.json

  /region/{region}:
    uriParameters:
      region:
        description: "Region name which is region identifier"
        type: string

    /status/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Overview of region's services status"
        responses:
          200:
            body:
              schema: !include schemas/200.json
              example: !include response_examples/200/status.json
          404:
            body:
              schema: !include schemas/404.json
              example: !include response_examples/404/region.json

    /status/health/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region health data aggregated per service"
        responses:
          200:
            body:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_region_health.json
          404:
            body:
              schema: !include schemas/404.json
              example: !include response_examples/404/region.json

    /status/availability/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region availability data aggregated per service"
        responses:
          200:
            body:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_region_availability.json
          404:
            body:
              schema: !include schemas/404.json
              example: !include response_examples/404/region.json

    /status/performance/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region performance data aggregated per service"
        responses:
          200:
            body:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_region_performance.json
          404:
            body:
              schema: !include schemas/404.json
              example: !include response_examples/404/region.json

    /infra:
      get:
        description: "Information about region's infrastructure services"
        responses:
          200:
            body:
              schema: !include schemas/200.json
              example: !include response_examples/200/infra.json
          404:
            body:
              schema: !include schemas/404.json
              example: !include response_examples/404/region.json

  /status/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Overview data aggregated per region"
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/status.json

  /status/health/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Health data aggregated per region"
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/status_health.json

  /status/availability/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Availability data aggregated per region"
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/status_availability.json

  /status/performance/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Performance data aggregated per region"
      responses:
        200:
          body:
            schema: !include schemas/200.json
            example: !include response_examples/200/status_performance.json

#%RAML 0.8

title: "Portal API - DRAFT!!!"
version: v1
mediaType: application/json

/api:
  get:
    description: "List of available versions"
    responses:
      200:
        body:
          application/json:
            schema: !include schemas/200.json
            example: !include response_examples/200/versions.json

/api/{version}:
  /regions:
    get:
      description: List of regions
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/regions.json

  /regions/detailed:
    get:
      description: "Detailed information about regions."
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/regions_detailed.json

  /region/{region}:
    uriParameters:
      region:
        description: "Region name which is region identifier"
        type: string

    /status/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Overview of region's services status"
        responses:
          200:
            body:
              application/json:
                schema: !include schemas/200.json
                example: !include response_examples/200/status.json
          404:
            body:
              application/json:
                schema: !include schemas/404.json
                example: !include response_examples/404/region.json

    /status/health/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region health data aggregated per service"
        responses:
          200:
            body:
              application/json:
                schema: !include schemas/200.json
                example: !include response_examples/200/status_region_health.json
          404:
            body:
              application/json:
                schema: !include schemas/404.json
                example: !include response_examples/404/region.json

    /status/availability/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region availability data aggregated per service"
        responses:
          200:
            body:
              application/json:
                schema: !include schemas/200.json
                example: !include response_examples/200/status_region_availability.json
          404:
            body:
              application/json:
                schema: !include schemas/404.json
                example: !include response_examples/404/region.json

    /status/performance/{period}:
      uriParameters:
        period:
          description: "Return data for specific period: day, week, month"
          type: string
      get:
        description: "Region performance data aggregated per service"
        responses:
          200:
            body:
              application/json:
                schema: !include schemas/200.json
                example: !include response_examples/200/status_region_performance.json
          404:
            body:
              application/json:
                schema: !include schemas/404.json
                example: !include response_examples/404/region.json

    /infra:
      get:
        description: "Information about region's infrastructure services"
        responses:
          200:
            body:
              application/json:
                schema: !include schemas/200.json
                example: !include response_examples/200/infra.json
          404:
            body:
              application/json:
                schema: !include schemas/404.json
                example: !include response_examples/404/region.json

  /status/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Overview data aggregated per region"
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/status.json

  /status/health/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Health data aggregated per region"
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_health.json

  /status/availability/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Availability data aggregated per region"
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_availability.json

  /status/performance/{period}:
    uriParameters:
      period:
        description: "Return data for specific period: day, week, month"
        type: string
    get:
      description: "Performance data aggregated per region"
      responses:
        200:
          body:
            application/json:
              schema: !include schemas/200.json
              example: !include response_examples/200/status_performance.json


Fix spec.

Fix spec.

#%RAML 0.8

title: Weather app API
baseUri: http://localhost/api/{version}
version: v0

/weather:
	description: |
		Возвращает информайию о погоде.
	queryParameters:
		city_id:
			type: integer
			required: true
			description: |
				Id города, погодные условия которого запрошены.
	get:
		responses:
			200:
				body:
					application/json:
						schema: |
							{
								"$schema": "http://json-schema.org/schema",
								"type": "object",
								"properties": {
									"temperature": {
										"type": "number",

									},
									"windVelocity": {
										"type": "number"
									},
									"windDirection": {
										"type": "string",
										"pattern": "^(S{1,2}|N{1,2})(E{1,2}|W{1,2})$"
									},
									"outOfDate": {
										"type": "boolean"
									}
								},
								"required": ["temperature","windVelocity","windDirection"]
							}
			404:

/cloth:
	/item/{item_id}:
		get:
			description: |
				Возвращает информацию о предмете гардероба.
			responses:
				200:
					body:
						application/json:
							schema: |
								{
									"$schema": "http://json-schema.org/schema",
									"type": "object",
									"description": "Описание предмета гардероба."
									"properties": {
										"name": {
											"type": "string",
											"description": "Название"
										},
										"description": {
											"type": "string",
											"description": "Текст - описание"
										},
										"group": {
											"type": "string",
											"description": "Группа. Определяет, где рисовать картинку."
										},
										"img": {
											"type": "string",
											"description": "URL файла картинки."
										}
									},
									required: ["name","description","group","layer"]
								}
				404:
	/choose:
		get:
			description: |
				Выбирает набор предметов одежды к заданным погодным условиям.
			queryParameters:
				season:
					enum: ["winter","spring","summer","autumn"]
					required: false
					description: |
						Время года (пока не обязательно).
				temperature:
					type: number
					required: true
					description: |
						Температура.
				windVelocity:
					type: number
					required: false
					description: |
						Скорость ветра (пока не обязательно).
			responses:
				200:
					body:
						application/json:
							schema: |
								{
									"$schema": "http://json-schema.org/schema",
									"type": "array",
									"items": {
										"type": "integer"
									}
								}

#%RAML 0.8

title: Weather app API
baseUri: http://localhost/api/{version}
version: v0

/weather:
	description: |
		Возвращает информайию о погоде.
	queryParameters:
		city_id:
			type: integer
			required: true
			description: |
				Id города, погодные условия которого запрошены.
	get:
		responses:
			200:
				body:
					application/json:
						schema: |
							{
								"$schema": "http://json-schema.org/schema",
								"type": "object",
								"properties": {
									"temperature": {
										"type": "number",

									},
									"windVelocity": {
										"type": "number"
									},
									"windDirection": {
										"type": "string",
										"pattern": "^(S{1,2}|N{1,2})(E{1,2}|W{1,2})$"
									}
								},
								"required": ["temperature","windVelocity","windDirection"]
							}
			404:

/cloth:
	/item/{item_id}:
		get:
			description: |
				Возвращает информацию о предмете гардероба.
			responses:
				200:
					body:
						application/json:
							schema: |
								{
									"$schema": "http://json-schema.org/schema",
									"type": "object",
									"description": "Описание предмета гардероба."
									"properties": {
										"name": {
											"type": "string",
											"description": "Название"
										},
										"description": {
											"type": "string",
											"description": "Текст - описание"
										},
										"group": {
											"type": "string",
											"description": "Группа. Определяет, где рисовать картинку."
										},
										"img": {
											"type": "string",
											"description": "URL файла картинки."
										}
									},
									required: ["name","description","group","layer"]
								}
				404:
	/choose:
		get:
			description: |
				Выбирает набор предметов одежды к заданным погодным условиям.
			queryParameters:
				season:
					enum: ["winter","spring","summer","autumn"]
					required: false
					description: |
						Время года (пока не обязательно).
				temperature:
					type: number
					required: true
					description: |
						Температура.
				windVelocity:
					type: number
					required: false
					description: |
						Скорость ветра (пока не обязательно).
			responses:
				200:
					body:
						application/json:
							schema: |
								{
									"$schema": "http://json-schema.org/schema",
									"type": "array",
									"items": {
										"type": "integer"
									}
								}