Added info about lang query parameter

Added info about lang query parameter

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
        required: false
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
        required: false
      senderLogo:
        type: string
        required: false
      totalListPrice:
        type: string
        required: false
      totalContractPrice:
        type: string
        required: false
      listPricePackageCount:
        type: string
        required: false
      contractPricePackageCount:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
        required: false
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      listPrice:
        type: string
        required: false
      contractPrice:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      pickupCode:
        type: string
        required: false
      shelfNumber:
        type: string
        required: false
      dateOfReturn:
        type: string
        required: false
      dateOfEstimatedDelivery:
        type: string
        required: false
      estimatedTimeSpanOfDelivery:
        type: EtaMlTimeSpan
        required: false
      dateOfDelivery:
        type: string
        required: false
      senderName:
        type: string
        required: false
      senderAddress:
        type: Address
        required: false
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: AdditionalService[]
        required: false
      requestPackage:
        type: requestedPackageType
        required: false
  Event:
    type: object
    properties:
      description:
        type: string
      status:
        type: string
      lmEventCode:
        type: string
        required: false
      recipientSignature:
        type: recipientSignatureType
      unitId:
        type: string
      unitInformationUrl:
        type: string
        required: false
      unitType:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
      gpsXCoordinate:
        type: string
        required: false
      gpsYCoordinate:
        type: string
        required: false
      gpsMapUrl:
        type: string
        required: false
  Address:
    type: object
    properties:
      addressLine1:
        type: string
      addressLine2:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
  requestedPackageType:
      type: object
      properties:
        userEmail:
          type: string
        requestedPackageOn:
          type: string
        caseId:
          type: string
        hasBeenRequested:
          type: string
  AdditionalService:
    type: object
    properties:
      id:
        type: string
      description:
        type: string
      amount:
        type: string
      currencyCode:
        type: string
      longDescription:
        type: string
        required: false
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  recipientSignatureType:
    type: object
    properties:
      name:
        type: string
      linkToImage:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false
  EtaMlTimeSpan:
    type: object
    properties:
      startTime:
        type: string
        required: false
      endTime:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    ### Select version by request-header
    Use the normal URL but add the following request-header:

    | Header | Example |
    |:-------|:--------|
    | `api-version` | `2` |

    #### Example request
    ```
    curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT
    ```

    ### Select version by URL
    Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

    | Application | URL example |
    |:-------|:--------|
    | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
    | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

    You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

    | URI request | Response type | Example |
    |:-------|:--------|:--------|
    | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
    | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

    #### Example request
    ```
    curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT
    ```

- title: Authentication
  content: |
    If you have a Mybring user, you can perform authenticated requests. They have the following benefits:
    - More information about parcels:
      - Price
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    To make authenticated Tracking API requests, you will have to use the endpoint [https://api.bring.com/tracking/api/](https://api.bring.com/tracking/api/). You also 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.

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```

- title: JSON API
  content: |
      We follow the [JSON API specification](http://jsonapi.org/) with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
      lang:
        description: Choose one of the following languages (en, no, sv, dk) to display the page information in respectively english, norwegian, swedish or danish
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading. |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been cancelled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country. |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender. |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.json
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.json
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.xml
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.xml
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.xml

#%RAML 1.0
---
title: Tracking API
version: v2
baseUri: https://tracking.bring.com/api
types:
  Consignment:
    type: object
    properties:
      consignmentSet:
        type: ConsignmentSet
      apiVersion:
        type: ApiVersion
  ConsignmentSet:
    type: object
    description: ?
    properties:
      consignmentId:
        type: string
      previousConsignmentId:
        type: string
        required: false
      packageSet:
        type: Package[]
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
        required: false
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
        required: false
      senderLogo:
        type: string
        required: false
      totalListPrice:
        type: string
        required: false
      totalContractPrice:
        type: string
        required: false
      listPricePackageCount:
        type: string
        required: false
      contractPricePackageCount:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  Package:
    type: object
    properties:
      statusDescription:
        type: string
      descriptions:
        type: string[]
        required: false
      packageNumber:
        type: string
      previousPackageNumber:
        type: string
      productName:
        type: string
      productCode:
        type: string
      productLink:
        type: string
        required: false
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      listPrice:
        type: string
        required: false
      contractPrice:
        type: string
        required: false
      currencyCode:
        type: string
        required: false
      pickupCode:
        type: string
        required: false
      shelfNumber:
        type: string
        required: false
      dateOfReturn:
        type: string
        required: false
      dateOfEstimatedDelivery:
        type: string
        required: false
      estimatedTimeSpanOfDelivery:
        type: EtaMlTimeSpan
        required: false
      dateOfDelivery:
        type: string
        required: false
      senderName:
        type: string
        required: false
      senderAddress:
        type: Address
        required: false
      recipientAddress:
        type: Address
        required: false
      recipientHandlingAddress:
        type: Address
        required: false
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: AdditionalService[]
        required: false
      requestPackage:
        type: requestedPackageType
        required: false
  Event:
    type: object
    properties:
      description:
        type: string
      status:
        type: string
      lmEventCode:
        type: string
        required: false
      recipientSignature:
        type: recipientSignatureType
      unitId:
        type: string
      unitInformationUrl:
        type: string
        required: false
      unitType:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
      gpsXCoordinate:
        type: string
        required: false
      gpsYCoordinate:
        type: string
        required: false
      gpsMapUrl:
        type: string
        required: false
  Address:
    type: object
    properties:
      addressLine1:
        type: string
      addressLine2:
        type: string
      postalCode:
        type: string
      city:
        type: string
      countryCode:
        type: string
      country:
        type: string
  requestedPackageType:
      type: object
      properties:
        userEmail:
          type: string
        requestedPackageOn:
          type: string
        caseId:
          type: string
        hasBeenRequested:
          type: string
  AdditionalService:
    type: object
    properties:
      id:
        type: string
      description:
        type: string
      amount:
        type: string
      currencyCode:
        type: string
      longDescription:
        type: string
        required: false
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  recipientSignatureType:
    type: object
    properties:
      name:
        type: string
      linkToImage:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        type: string
        required: false
  EtaMlTimeSpan:
    type: object
    properties:
      startTime:
        type: string
        required: false
      endTime:
        type: string
        required: false

documentation:
- title: Introduction
  content: |
      The Tracking API provides the opportunity to track shipments by reference, package or shipment number.
      It is an easy way to display details and the status of shipments.
      The information available in this API is the same that is publically available from the [Tracking web site](http://tracking.bring.com/).

- title: Versioning
  content: |
    Latest Tracking API version: `v2`

    We encourage you to use the latest version of our API all time.  Of course, we keep the previous version for some time so that you will get enough time to convert your application. This API supports versioning by two means.

    ### Select version by request-header
    Use the normal URL but add the following request-header:

    | Header | Example |
    |:-------|:--------|
    | `api-version` | `2` |

    #### Example request
    ```
    curl -H "api-version: 2" https://tracking.bring.com/api/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT
    ```

    ### Select version by URL
    Use the normal URL, but add **```{v1, v2}```** to the URL. Example:

    | Application | URL example |
    |:-------|:--------|
    | Open tracking | https://tracking.bring.com/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |
    | Logged-in tracking | https://api.bring.com/tracking/api/**v2**/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT |

    You can verify that your request were used correctly by certifying that the response contains an element based on the request type:

    | URI request | Response type | Example |
    |:-------|:--------|:--------|
    | tracking.json | `application/json; charset=utf-8` | `{"apiVersion": "2"}` |
    | tracking.xml | `application/xml;charset=utf-8` | `<ApiVersion>2</ApiVersion>` |

    #### Example request
    ```
    curl -v https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT
    ```

- title: Authentication
  content: |
    If you have a Mybring user, you can perform authenticated requests. They have the following benefits:
    - More information about parcels:
      - Price
      - Name
      - Address
      - Signatures for proof of delivery
    - Less strict rate limits

    To make authenticated Tracking API requests, you will have to use the endpoint [https://api.bring.com/tracking/api/](https://api.bring.com/tracking/api/). You also 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.

- title: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```

- title: JSON API
  content: |
      We follow the [JSON API specification](http://jsonapi.org/) with one
      exception: we allow media type to be specified as `application/json`
      instead of `application/vnd.api+json`.

/{version}/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  description: Get information about an existing shipment based on a tracking number, shipment number or reference.
  uriParameters:
    version:
      enum: [ v1, v2 ]
      description: v1 is deprecated and will be removed soon. Use v2 when requesting the tracking API
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      X-Bring-Client-URL:
        description: A URL that sort of identifies where you're using the APIs.
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT, 370000000000000001
      aktornummer:
        description: Represents a valid customer number registered with Posten
        type: string
        required: false
        example: "12345678901"
      callback:
        description: JSONP callback function name
        type: string
        required: false
    responses:
      200:
        displayName: Successful response
        description: |
          For testing you can use "TESTPACKAGE-AT-PICKUPPOINT" as the tracking number to generate test results. For real tracking this must be a valid number.

          You can find an XSD for the XML response here: [tracking-v2.xsd](https://tracking.bring.com/schema/api/tracking-v2.xsd).

          A parcel has a number of events connected to it during its travel. Here are a list of current event statuses that can be returned.

          | Event | Description |
          |:-------|:--------|
          | `ARRIVED_DELIVERY` | Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading. |
          | `ARRIVED_COLLECTION` | Arrived for collection at pickup point |
          | `ATTEMPTED_DELIVERY` | The package has been attempted delivered at the door. Depending on the service it will be tried again or sent to closest pickup point. |
          | `CUSTOMS` | Package is in customs clearance. |
          | `COLLECTED` | The parcel has been collected at pickup address. |
          | `DELIVERED` | Package has been delivered. |
          | `DELIVERED_SENDER` | Package has been returned to the sender |
          | `DELIVERY_CANCELLED` | Home delivery has been cancelled by the customer. |
          | `DELIVERY_CHANGED` | Date for Home delivery has been changed by customer. |
          | `DELIVERY_ORDERED` | Home delivery has been ordered |
          | `DEVIATION` | Deviation in production. Something wrong has happened and there is a probability for delay. |
          | `HANDED_IN` | Package has been handed in to Bring. |
          | `INTERNATIONAL` | Package has been sent from origin country or arrived at destination country. |
          | `IN_TRANSIT` | Package is in transit. |
          | `NOTIFICATION_SENT` | Notification for this package has been sent by sms, push and/or mail. This can be informational notifications and action notification like pickup notice. |
          | `PRE_NOTIFIED` | EDI message for the package has been received by Bring. |
          | `READY_FOR_PICKUP` | Package has arrived at pickup point. |
          | `RETURN` | The package has been returned to sender. |
          | `TRANSPORT_TO_RECIPIENT` | Package has been loaded for delivery to the recipient. |
          | `TERMINAL` | The package is now registered/arrived at inbound/outbound storage terminal |
          | `UNKNOWN` | Represents unknown / undefined events |

        body:
          application/json:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below shows an successful deliverance of a package at a pickup point
                value: !include examples/successful.json
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.json
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.json
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.json
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.json
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.json
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.json
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.json
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.json
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.json
          application/xml:
            type: Consignment
            examples:
              successful:
                displayName: Successful
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/successful.xml
              unsuccessful:
                displayName: Unsuccessful request
                description: Returned upon no search responses being returned for the request itself
                value: !include examples/unsuccessful.xml
              badRequest:
                displayName: Bad request
                description: Returned when query requested is invalid
                value: !include examples/bad_request.xml
              serviceUnavailable:
                displayName: Service unavailable
                description: Returned when there are too many requests on server
                value: !include examples/service_unavailable.xml
              unspeciified:
                displayName: Technical Erroor
                description: Returned when there is some technical error
                value: !include examples/unspecified.xml
              notification_received:
                displayName: Unreceived package, with notification regarding EDI
                description: The example below is showing a package that have been EDI notified, but is not received by Bring.
                value: !include examples/notification_received.xml
              waiting_at_pup:
                displayName: Waiting at Pickup Point
                description: The example below is showing a package waiting for the recipient to collect it at a pickup point
                value: !include examples/waiting_at_pup.xml
              loaded_for_delivery:
                displayName: Package loaded for delivery
                description: The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
                value: !include examples/loaded_for_delivery.xml
              delivered:
                displayName: Package delivered to customer
                description: The example below is showing a package that has been delivered to the reciepient.
                value: !include examples/delivered.xml
              estimatedTimeOfArrival:
                displayName: Package with estimated time of arrival.
                description: The example below is showing a package with estimated arrival time window of delivery.
                value: !include examples/successfulWithEta.xml


Updated api spec

Updated api spec

#%RAML 0.8
title: ChewCrew
version: v1
baseUri: http://chewcrew.io/{version}

/preferences:
  /categories:
    get:
      description: Get all category type preferences (BBQ, Chinese, Pizza, etc.)

/sessions:
  post:
    description: Create a voting session
    responses:
      200:
        body:
          application/json:
            schema: |
              {
              "$schema": "http://json-schema.org/schema",
              "type": "object",
              "description": "A voting session",
              "properties": {
              "session": "Session UUID",
              "session": { "type": "string" }
              }}
  /{id}:
    /start:
      post:
        description: Starts the voting session
    /end:
      post:
        description: Forcefully ends a voting session
    get:
      description: Retrieve a voting session
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "A voting session",
                "properties": {
                "voterId": "Current voters unique UUID",
                "voterId": {"type": "string"},
                "voters": "Total number of unique voters participating",
                "voters": {
                  "type": "array",
                  "name": {"type": "string"}
                  },
                "voted": "Total number of current votes",
                "voted": {"type": "int"},
                "choices": "Will be populated once the voting session has started",
                "choices": {
                  "type": "array",
                  "items": {"type" : "string"},
                  "minItems": 3,
                  "uniqueItems": true
                  },
                "result": "The winning result. Will be populating once all voters have voted.",
                "result": {"type": "string"}
                }}
    put:
      description: Update a voting session (will be done when voters first enter a session)
      queryParameters:
        name:
          description: Voters name
        preferences:
          description: Preferences to add
    post:
      description: Submit a vote to a voting session
      queryParameters:
        choice:
          description: Vote to submit
        voterId:
          description: UUID of voter

#%RAML 0.8
title: ChewCrew
version: v1
baseUri: http://chewcrew.io/{version}

/preferences:
  /categories:
    get:
      description: Only display category type preferences (BBQ, Chinese, Pizza, etc.)

/sessions:
  post:
    description: Create a voting session
    queryParameters:

  /{id}:
    /start:
      post:
        description: Starts the voting session
    /end:
      post:
        description: Forcefully ends a voting session
    get:
      description: Retrieve a voting session
      responses:
        200:
          body:
            application/json:
              schema: |
                {
                "$schema": "http://json-schema.org/schema",
                "type": "object",
                "description": "A voting session",
                "properties": {
                "voters": "Total number of unique voters participating",
                "voters": {
                  "type": "array",
                  "name": {"type": "string"}
                  },
                "voted": "Total number of current votes",
                "voted": {"type": "int"},
                "choices": "Will be populated once the voting session has started",
                "choices": {
                  "type": "array",
                  "items": {"type" : "string"},
                  "minItems": 3,
                  "uniqueItems": true
                  },
                "result": "The winning result. Will be populating once all voters have voted.",
                "result": {"type": "string"}
                }}
    put:
      description: Update a voting session (will be done when voters first enter a session)
      queryParameters:
        name:
          description: Voters name
        preferences:
          description: Preferences to add
        location:
          description: Location to add
    post:
      description: Submit a vote to a voting session
      queryParameters:
        choice:
          description: Vote to submit


Update service title in RAML

Update service title in RAML

#%RAML 0.8
title: Wishlist Boilerplate Service
baseUri: http://localhost/
version: v1
mediaType:  application/json

schemas:
  - wishlists: !include wishlists.json
  - wishlist: !include wishlist.json
  - wishlistItem: !include wishlistItem.json
  - error: !include https://api.yaas.io/patterns/v1/schema-error-message.json

traits:
  - !include https://api.yaas.io/patterns/v2/trait-app-aware.yaml

resourceTypes:
  - !include https://api.yaas.io/patterns/v1/resource-type-element.yaml
  - !include https://api.yaas.io/patterns/v1/resource-type-collection.yaml

/wishlists:
  type: collection
  is: [appAware]
  get:
    description: Gets all wishlists
    responses:
      200:
        body:
          application/json:
            example: !include wishlists-example.json
  post:
    description: Creates a new wishlist
    body:
      application/json:
        example: !include wishlist-example.json

  /{wishlistId}:
    type: element
    is: [appAware]
    uriParameters:
      wishlistId:
        description: the id of the wishlist to work on
        example: 784hti8ey
        type: string
    get:
      description: Gets a wishlist
      responses:
        200:
          body:
            application/json:
              example: !include wishlist-example.json

    put:
      description: Updates a wishlist
      body:
        application/json:
          example: !include wishlist-example.json

    delete:
      description: Deletes a wishlist

#%RAML 0.8
title: hybris Service Archetype
baseUri: http://localhost/
version: v1
mediaType:  application/json

schemas:
  - wishlists: !include wishlists.json
  - wishlist: !include wishlist.json
  - wishlistItem: !include wishlistItem.json
  - error: !include https://api.yaas.io/patterns/v1/schema-error-message.json

traits:
  - !include https://api.yaas.io/patterns/v2/trait-app-aware.yaml

resourceTypes:
  - !include https://api.yaas.io/patterns/v1/resource-type-element.yaml
  - !include https://api.yaas.io/patterns/v1/resource-type-collection.yaml

/wishlists:
  type: collection
  is: [appAware]
  get:
    description: Gets all wishlists
    responses:
      200:
        body:
          application/json:
            example: !include wishlists-example.json
  post:
    description: Creates a new wishlist
    body:
      application/json:
        example: !include wishlist-example.json

  /{wishlistId}:
    type: element
    is: [appAware]
    uriParameters:
      wishlistId:
        description: the id of the wishlist to work on
        example: 784hti8ey
        type: string
    get:
      description: Gets a wishlist
      responses:
        200:
          body:
            application/json:
              example: !include wishlist-example.json

    put:
      description: Updates a wishlist
      body:
        application/json:
          example: !include wishlist-example.json

    delete:
      description: Deletes a wishlist


Correct WireMock version number in the RAML spec

#%RAML 0.8
---
title: WireMock
version: 2.6.0
mediaType: application/json

documentation:
  - title: WireMock admin
    content: |
       The WireMock admin API.

schemas:
  - stubMapping: !include schemas/stub-mapping.schema.json
  - stubMappings: !include schemas/stub-mappings.schema.json
  - requestPattern: !include schemas/request-pattern.schema.json

/__admin/mappings:
  description: Stub mappings

  get:
    description: Get all stub mappings

    queryParameters:
      limit:
        displayName: Query limit
        type: number
        description: The maximum number of results to return
        example: 10
        required: false
      offset:
        displayName: Query offset
        type: number
        description: The start index of the results to return
        example: 25
        required: false

    responses:
      200:
        description: All stub mappings
        body:
          application/json:
            schema: stubMappings
            example: !include examples/stub-mappings.example.json

  post:
    description: Create a new stub mapping
    body:
      application/json:
        example: !include examples/stub-mapping-no-id.example.json
        schema: stubMapping

    responses:
      201:
        description: Successfully created
        body:
          application/json:
            example: !include examples/stub-mapping-with-id.example.json
            schema: stubMapping

  delete:
    description: Delete all stub mappings
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /reset:
      description: Stub mappings
      post:
        description: Reset stub mappings (restore to defaults defined back the backing store)
        responses:
          200:
            description: Successfully reset

  /{stubMappingId}:
    description: Single stub mapping
    get:
      description: Get a single stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/stub-mapping-with-id.example.json
              schema: stubMapping

    uriParameters:
      stubMappingId:
        required: true
        example: 730d3e32-d098-4169-a20c-554c3bedce58
        displayName: Stub mapping ID
        description: The UUID of stub mapping

    put:
      description: Update an existing stub mapping
      body:
        application/json:
          example: !include examples/stub-mapping-no-id.example.json
          schema: stubMapping

      responses:
        200:
          body:
            application/json:
              schema: stubMapping
              example: !include examples/stub-mapping-with-id.example.json

    delete:
      description: Delete a stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/empty.example.json

  /save:
    description: Stub mappings
    post:
      description: Save all persistent stub mappings to the backing store
      responses:
        200:
          description: Successfully removed

/__admin/scenarios:
  description: Scenarios support modelling of stateful behaviour

  /reset:
    description: Scenarios
    post:
      description: Reset the state of all scenarios
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

/__admin/requests:
  description: Logged requests and responses received by the mock service

  get:
    description: Get received requests
    queryParameters:
      limit:
        displayName: Query limit
        description: The maximum number of results to return
        example: 10
      since:
        example: 2016-10-05T12:33:01Z
        displayName: Since date
        description: Only return logged requests after this date

    responses:
      200:
        body:
          application/json:
            example: !include examples/serve-events.example.json
  delete:
    description: Delete all received requests
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /{requestId}:
    description: Single logged request
    get:
      responses:
        200:
          body:
            application/json:
              example: !include examples/request.example.json

    uriParameters:
      requestId:
        displayName: Request ID
        description: The UUID of the logged request
        required: true
        example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

  /reset:
    description: Request journal
    post:
      description: Empty the request journal
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

  /count:
    description: Request journal
    post:
      description: Count requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Number of matching requests
          body:
            application/json:
              example: !include examples/request-count.example.json

  /find:
    post:
      description: Retrieve details of requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Matching request details
          body:
            application/json:
              example: !include examples/requests.example.json

  /unmatched:
    get:
      description: Get details of logged requests that weren't matched by any stub mapping
      responses:
        200:
          description: Unmatched request details
          body:
            application/json:
              example: !include examples/requests.example.json

    /near-misses:
      get:
        description: Retrieve near-misses for all unmatched requests
        responses:
          200:
            description: Top 3 (at most) near misses for each unmatched request
            body:
              application/json:
                example: !include examples/near-misses.example.json

/__admin/near-misses:
  description: Near misses allow querying of received requests or request patterns according to similarity

  /request:
    post:
      description: Find at most 3 near misses for closest stub mappings to the specified request
      body:
        application/json:
          example: !include examples/logged-request.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

  /request-pattern:
    description: Near misses
    post:
      description: Find at most 3 near misses for closest logged requests to the specified request pattern
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

/__admin/settings:
  description: Global settings
  post:
    description: Update global settings
    body:
      application/json:
        example: |
          {
              "fixedDelay": 500
          }

    responses:
      200:
        description: Settings successfully updated

/__admin/shutdown:
  description: Shutdown function
  post:
    description: Shutdown the WireMock server
    responses:
      200:
        description: Server will be shut down

#%RAML 0.8
---
title: WireMock
version: 2.3.2
mediaType: application/json

documentation:
  - title: WireMock admin
    content: |
       The WireMock admin API.

schemas:
  - stubMapping: !include schemas/stub-mapping.schema.json
  - stubMappings: !include schemas/stub-mappings.schema.json
  - requestPattern: !include schemas/request-pattern.schema.json

/__admin/mappings:
  description: Stub mappings

  get:
    description: Get all stub mappings

    queryParameters:
      limit:
        displayName: Query limit
        type: number
        description: The maximum number of results to return
        example: 10
        required: false
      offset:
        displayName: Query offset
        type: number
        description: The start index of the results to return
        example: 25
        required: false

    responses:
      200:
        description: All stub mappings
        body:
          application/json:
            schema: stubMappings
            example: !include examples/stub-mappings.example.json

  post:
    description: Create a new stub mapping
    body:
      application/json:
        example: !include examples/stub-mapping-no-id.example.json
        schema: stubMapping

    responses:
      201:
        description: Successfully created
        body:
          application/json:
            example: !include examples/stub-mapping-with-id.example.json
            schema: stubMapping

  delete:
    description: Delete all stub mappings
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /reset:
      description: Stub mappings
      post:
        description: Reset stub mappings (restore to defaults defined back the backing store)
        responses:
          200:
            description: Successfully reset

  /{stubMappingId}:
    description: Single stub mapping
    get:
      description: Get a single stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/stub-mapping-with-id.example.json
              schema: stubMapping

    uriParameters:
      stubMappingId:
        required: true
        example: 730d3e32-d098-4169-a20c-554c3bedce58
        displayName: Stub mapping ID
        description: The UUID of stub mapping

    put:
      description: Update an existing stub mapping
      body:
        application/json:
          example: !include examples/stub-mapping-no-id.example.json
          schema: stubMapping

      responses:
        200:
          body:
            application/json:
              schema: stubMapping
              example: !include examples/stub-mapping-with-id.example.json

    delete:
      description: Delete a stub mapping
      responses:
        200:
          body:
            application/json:
              example: !include examples/empty.example.json

  /save:
    description: Stub mappings
    post:
      description: Save all persistent stub mappings to the backing store
      responses:
        200:
          description: Successfully removed

/__admin/scenarios:
  description: Scenarios support modelling of stateful behaviour

  /reset:
    description: Scenarios
    post:
      description: Reset the state of all scenarios
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

/__admin/requests:
  description: Logged requests and responses received by the mock service

  get:
    description: Get received requests
    queryParameters:
      limit:
        displayName: Query limit
        description: The maximum number of results to return
        example: 10
      since:
        example: 2016-10-05T12:33:01Z
        displayName: Since date
        description: Only return logged requests after this date

    responses:
      200:
        body:
          application/json:
            example: !include examples/serve-events.example.json
  delete:
    description: Delete all received requests
    responses:
      200:
        description: Successfully deleted
        body:
          application/json:
            example: !include examples/empty.example.json

  /{requestId}:
    description: Single logged request
    get:
      responses:
        200:
          body:
            application/json:
              example: !include examples/request.example.json

    uriParameters:
      requestId:
        displayName: Request ID
        description: The UUID of the logged request
        required: true
        example: 12fb14bb-600e-4bfa-bd8d-be7f12562c99

  /reset:
    description: Request journal
    post:
      description: Empty the request journal
      responses:
        200:
          description: Successfully reset
          body:
            application/json:
              example: !include examples/empty.example.json

  /count:
    description: Request journal
    post:
      description: Count requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Number of matching requests
          body:
            application/json:
              example: !include examples/request-count.example.json

  /find:
    post:
      description: Retrieve details of requests logged in the journal matching the specified criteria
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Matching request details
          body:
            application/json:
              example: !include examples/requests.example.json

  /unmatched:
    get:
      description: Get details of logged requests that weren't matched by any stub mapping
      responses:
        200:
          description: Unmatched request details
          body:
            application/json:
              example: !include examples/requests.example.json

    /near-misses:
      get:
        description: Retrieve near-misses for all unmatched requests
        responses:
          200:
            description: Top 3 (at most) near misses for each unmatched request
            body:
              application/json:
                example: !include examples/near-misses.example.json

/__admin/near-misses:
  description: Near misses allow querying of received requests or request patterns according to similarity

  /request:
    post:
      description: Find at most 3 near misses for closest stub mappings to the specified request
      body:
        application/json:
          example: !include examples/logged-request.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

  /request-pattern:
    description: Near misses
    post:
      description: Find at most 3 near misses for closest logged requests to the specified request pattern
      body:
        application/json:
          schema: requestPattern
          example: !include examples/request-pattern.example.json

      responses:
        200:
          description: Near misses matching criteria
          body:
            application/json:
              example: !include examples/near-misses.example.json

/__admin/settings:
  description: Global settings
  post:
    description: Update global settings
    body:
      application/json:
        example: |
          {
              "fixedDelay": 500
          }

    responses:
      200:
        description: Settings successfully updated

/__admin/shutdown:
  description: Shutdown function
  post:
    description: Shutdown the WireMock server
    responses:
      200:
        description: Server will be shut down


backport of pragma deprecated from network overhaul branch

Summary: Allow Marathon devs to annotate API fields/types as deprecated.

Test Plan: sbt ramlGenerate

Reviewers: aquamatthias, jeschkies

Reviewed By: aquamatthias, jeschkies

Subscribers: jenkins, marathon-team

Differential Revision: https://phabricator.mesosphere.com/D290

#%RAML 1.0 Library
annotationTypes:
  asUpdateType:
    type: nil
    description: |
      Applies only to top-level object types (of type object). Instructs the RAML
      generator that all fields of this type should be wrapped with Option.
      DO NOT USE with generateUpdateType.
  generateUpdateType:
    type: string?
    description: |
      Applies only to top-level object types (of type object). Instructs the RAML
      generator to build a sibling XyzUpdate type (where Xyz is the name of the
      type to which this annoation is applied). If a value is provided here then
      it is used as the name of the generated update-type (instead of XyzUpdate).
  scalaType:
    type: string
    description: |
      Applies to enum types. Overrides the default scala-type name generated
      for the type to which it is applied.
  forceOptional:
    type: nil
    description: |
      Applies to all types. Instruct the RAML generator to force an optional type.
      This can be usefull especially for containers, where the empty container is different than the unspecified container.
  deprecated:
    type: string?
    description: |
      The field is deprecated.