Include removal of client-library references and updates the documentation for TrackingAPI

#%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
      recipientHandlingAddress:
        type: Address
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  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
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      pickupCode:
        type: string
      dateOfReturn:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      recipientAddress:
        type: Address
      recipientHandlingAddress:
        type: Address
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: object[]
        required: false
  Event:
    type: object
    properties:
      description: string
      status:
        type: string
      recipientSignature:
        type: NamedElement
      unitId:
        type: string
      unitType:
        type: string
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
  Address:
    type: object
    properties:
      addressLine1:
        type: string
        required: false
      addressLine2:
        type: string
        required: false
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        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: Formats
  content: |
    The Tracking API generates the following formats:
    - ```XML```
    - ```JSON```
    - ```JSONP```
- 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://mybring.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 are a Mybring user, you can authenticate requests to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of develiery
    - Less strict rate limiting

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests, and you have to use the endpoint

        https://www.mybring.com/tracking/api/
- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification 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/api/schema/sporing-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 product 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 canceled 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
              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
          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
              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

#%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
      recipientHandlingAddress:
        type: Address
      senderReference:
        type: string
      senderCustomerNumber:
        type: string
      senderCustomerMasterNumber:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      senderCustomerType:
        type: string
      recipientCustomerNumber:
        type: string
      recipientCustomerMasterNumber:
        type: string
      recipientCustomerType:
        type: string
      isPickupNoticeAvailable:
        type: boolean
      consignmentActionSet:
        type: ConsignmentAction
      totalWeightInKgs:
        type: number
      totalVolumeInDm3:
        type: number
  ApiVersion:
    type: object
  ConsignmentAction:
    type: object
    properties:
      actionType:
        type: string
      actionURL:
        type: string
  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
      brand:
        type: string
      lengthInCm:
        type: number
      widthInCm:
        type: number
      heightInCm:
        type: number
      volumeInDm3:
        type: number
      weightInKgs:
        type: number
      pickupCode:
        type: string
      dateOfReturn:
        type: string
      senderName:
        type: string
      senderAddress:
        type: Address
      recipientAddress:
        type: Address
      recipientHandlingAddress:
        type: Address
      eventSet:
        type: Event[]
      additionalServiceSet:
        type: object[]
        required: false
  Event:
    type: object
    properties:
      description: string
      status:
        type: string
      recipientSignature:
        type: NamedElement
      unitId:
        type: string
      unitType:
        type: string
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
      dateIso:
        type: string
      displayDate:
        type: string
      displayTime:
        type: string
      consignmentEvent:
        type: boolean
      insignificant:
        type: boolean
  Address:
    type: object
    properties:
      addressLine1:
        type: string
        required: false
      addressLine2:
        type: string
        required: false
      postalCode:
        type: string
        required: false
      city:
        type: string
        required: false
      countryCode:
        type: string
        required: false
      country:
        type: string
        required: false
  NamedElement:
    type: object
    properties:
      name:
        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 information available from the [Tracking web site](http://tracking.bring.com/).
      Response is available as either XML or JSON.

      *Oh by the way*, we also have a [Java client library](https://github.com/bring/bring-api-java) for the Tracking API.

- title: Versioning
  content: |
    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.

    - **Setting requst header with version number.**
      Use the normal URL but add the following Request Header. Example:

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

    - **Setting version number in the 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://mybring.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>` |

- title: Authentication
  content: |
    If you are a Mybring user, you can authenticate requests to the Tracking API. Authenticated requests have the following benefits:

    - More information about parcels:
      - Prices
      - Name
      - Address
      - Signatures for proof of develiery
    - Less strict rate limiting

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests, and you have to use the endpoint

        https://www.mybring.com/tracking/api/
- title: JSON API
  content: |
      We follow the [JSON API](http://jsonapi.org/) specification 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/api/schema/sporing-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 product 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 canceled 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
              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
          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
              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


updated tracking with version info

updated tracking with version info

#%RAML 0.8
---
title: Tracking API
baseUri: https://tracking.bring.com/api

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 information available from the [Tracking web site](http://tracking.bring.com/).
      Response is available as either XML or JSON.

      *Oh by the way*, we also have a [Java client library](https://github.com/bring/bring-api-java) for the Tracking API.

- title: Versioning
  content: |
    We encurrage 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 enought time to convert your application. This API supports versioning by two means.

    - **Setting requst header with version number.**
      Then you use the normal URL but add Request Header.

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

    - **Setting version number in the url.**
      Then you have to update the url by adding *v2*
      example for open tracking:
      https://tracking.bring.com/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT
      example for logged in tracking:
      https://mybring.com/tracking/api/v2/tracking.json?q=TESTPACKAGE-AT-PICKUPPOINT

      You can verify that you are doing it correctly by checking that the response should containt the element *"apiVersion": "2"*.

- title: Authentication
  content: |
    If you are a Mybring user, you can authenticate requests to the Tracking API. Authenticated requests have the following benefits:

    - You get more information about your parcels, for example prices, name, address and signatures for proof of develiery
    - Less strict rate limiting

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests, and you have to use the endpoint

        https://www.mybring.com/tracking/api/

/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  securedBy: [mybring_headers, null]
  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/api/schema/sporing-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.

      - ARRIVED_DELIVERY
        Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.

      - CUSTOMS

        Package is in customs clearance.
      - COLLECTED

        The parcel has been collected at pickup address.
      - DELIVERED

        Package has been delivered. This can be both to the receiver or returned to the sender.
      - DELIVERY_CANCELLED

      Home delivery has been canceled 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.

  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/testpackage.json
          application/xml:
            example: !include examples/testpackage.xml
      250:
        displayName: Status - notification received
        description: |
          The example below is showing a package that have been EDI notified, but is not received by Bring.
        body:
          application/json:
            example: !include examples/notification_received.json
          application/xml:
            example: !include examples/notification_received.xml
      251:
        displayName: Status - waiting at pickup point
        description: |
          The example below is showing a package waiting for the recipient to collect it at a pickup point
        body:
          application/json:
            example: !include examples/waiting_at_pup.json
          application/xml:
            example: !include examples/waiting_at_pup.xml
      252:
        displayName: Status - loaded for delivery
        description: |
          The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
        body:
          application/json:
            example: !include examples/loaded_for_delivery.json
          application/xml:
            example: !include examples/loaded_for_delivery.xml
      253:
        displayName: Status - delivered
        description: |
          The example below is showing a package that has been delivered to the reciepient.
        body:
          application/json:
            example: !include examples/delivered.json
          application/xml:
            example: !include examples/delivered.xml

#%RAML 0.8
---
title: Tracking API
baseUri: https://tracking.bring.com

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 information available from the [Tracking web site](http://tracking.bring.com/).
      Response is available as either XML or JSON.

      *Oh by the way*, we also have a [Java client library](https://github.com/bring/bring-api-java) for the Tracking API.

- title: Authentication
  content: |
    If you are a Mybring user, you can authenticate requests to the Tracking API. Authenticated requests have the following benefits:

    - You get more information about your parcels, for example signatures for proof of develiery
    - No rate limiting

    See the [getting started guide on authentication](/api/#authentication) if you're not sure what this means.

    | Header | Example | Comment |
    |:-------|:--------|:--------|
    | `X-MyBring-API-Uid` | `john.doe@example.com` | Mybring login ID |
    | `X-MyBring-API-Key` | `1234abc-abcd-1234-5678-abcd1234abcd ` | Mybring login's API key |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be present for authenticating requests, and you have to use the endpoint

        https://www.mybring.com/tracking/api/

/tracking{mediaTypeExtension}:
  displayName: Tracking endpoint
  securedBy: [mybring_headers, null]
  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-v1.xsd](https://tracking.bring.com/api/schema/sporing-v1.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.

      - ARRIVED_DELIVERY
        Arrived Delivery point - This is when a container arrives at recipients address, and can start unloading.

      - CUSTOMS

        Package is in customs clearance.
      - COLLECTED

        The parcel has been collected at pickup address.
      - DELIVERED

        Package has been delivered. This can be both to the receiver or returned to the sender.
      - DELIVERY_CANCELLED

      Home delivery has been canceled 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.

  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify application/xml
  get:
    description: Get information about a shipment
    queryParameters:
      q:
        description: Reference, package number, shipment number to search for
        type: string
        required: true
        example: TESTPACKAGE-AT-PICKUPPOINT
      callback:
        description: JSONP callback function name
        type: string
        required: false

    responses:
      200:
        displayName: Successful response
        body:
          application/json:
            example: !include examples/testpackage.json
          application/xml:
            example: !include examples/testpackage.xml
      250:
        displayName: Status - notification received
        description: |
          The example below is showing a package that have been EDI notified, but is not received by Bring.
        body:
          application/json:
            example: !include examples/notification_received.json
          application/xml:
            example: !include examples/notification_received.xml
      251:
        displayName: Status - waiting at pickup point
        description: |
          The example below is showing a package waiting for the recipient to collect it at a pickup point
        body:
          application/json:
            example: !include examples/waiting_at_pup.json
          application/xml:
            example: !include examples/waiting_at_pup.xml
      252:
        displayName: Status - loaded for delivery
        description: |
          The example below is showing a package that has been loaded on a distribution car for delivery to the reciepient.
        body:
          application/json:
            example: !include examples/loaded_for_delivery.json
          application/xml:
            example: !include examples/loaded_for_delivery.xml
      253:
        displayName: Status - delivered
        description: |
          The example below is showing a package that has been delivered to the reciepient.
        body:
          application/json:
            example: !include examples/delivered.json
          application/xml:
            example: !include examples/delivered.xml


removing REST GET related api endpoints information

#%RAML 1.0
---
title: Shipping Guide API
baseUri: https://api.bring.com/shippingguide

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: |
      Use this endpoint to get expected delivery, service categories and additional information.

      ### Measurements
      For cargo services(5100, 5300, 9100, CARGO), Weight is mandatory and one of the Volume / Load Meter / Dimensions / Number of Pallets is mandatory.

      Note: The prices for our revised services depends on volumetric weight: 5000, 5100, 5300, 5600, 5800, 4850 plus return services 9000, 9100, 9300 or 9600. For these services, dimensions (L/W/H) is needed to calculate the expected price correctly. Dimensions are also used to decide if handling fee or specialgoods fee will apply to the shipment. You might leave dimensions empty in your request, but be aware that returned prices might be incorrect.

  post:
    description: Get shipment prices and leadtime
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
        required: true
      X-MyBring-API-Key:
        description: Your user's API key
        required: true
      Content-Type:
        description: application/json
        required: true
    body:
      application/json:
        examples:
          restEstimatedDeliveryReq:
            displayName: Estimated delivery time request
            value: !include examples/rest_estimated_delivery_time_request.json
    responses:
      200:
        body:
          application/json:
            examples:
              restEstimateDeliveryRes:
                displayName: Estimated delivery time successful response
                value: !include examples/rest_estimated_delivery_time_response_200.json

/api/ws:
  displayName: SOAP
  description: |
      The SOAP Body follows the same XML Schema Definition (XSD) as stated above.
      ### Estimated delivery times
        To get estimated delivery times in the response, set `WithExpectedDelivery` and `WithEstimatedDeliveryTime` to true in the request along with specifying `PickupPoints`
      ### Request and response structure
        If you request shipping alternatives via the API your request and response will have to comply with the following schemas:

        [https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd)

        [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

  post:
    description: Use this endpoint to get same information as above REST API
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/xml)
    body:
      application/xml:
        examples:
          estimated_delivery_time_request:
            displayName: Estimated delivery time
            value: !include examples/soap_estimated_delivery_time_request.xml
    responses:
          200:
            displayName: Estimated delivery time successful response
            body:
              application/xml:
                examples:
                  estimated_delivery_time_response:
                    displayName: Estimated delivery time
                    value: !include examples/soap_estimated_delivery_time_response_200.xml

#%RAML 1.0
---
title: Shipping Guide API
baseUri: https://api.bring.com/shippingguide

/v2/products:
  displayName: Get shipment prices and estimated delivery
  description: |
      Use this endpoint to get expected delivery, service categories and additional information.

      ### Measurements
      For cargo services(5100, 5300, 9100, CARGO), Weight is mandatory and one of the Volume / Load Meter / Dimensions / Number of Pallets is mandatory.

      Note: The prices for our revised services depends on volumetric weight: 5000, 5100, 5300, 5600, 5800, 4850 plus return services 9000, 9100, 9300 or 9600. For these services, dimensions (L/W/H) is needed to calculate the expected price correctly. Dimensions are also used to decide if handling fee or specialgoods fee will apply to the shipment. You might leave dimensions empty in your request, but be aware that returned prices might be incorrect.

      ### REST POST vs GET
      There is both a POST and a GET endpoint for REST. We recommend using the POST endpoint over the GET one, as this is more likely to get all new features.

  post:
    description: Get shipment prices and leadtime
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
        required: true
      X-MyBring-API-Key:
        description: Your user's API key
        required: true
      Content-Type:
        description: application/json
        required: true
    body:
      application/json:
        examples:
          restEstimatedDeliveryReq:
            displayName: Estimated delivery time request
            value: !include examples/rest_estimated_delivery_time_request.json
    responses:
      200:
        body:
          application/json:
            examples:
              restEstimateDeliveryRes:
                displayName: Estimated delivery time successful response
                value: !include examples/rest_estimated_delivery_time_response_200.json

  get:
    description: Get shipment prices and leadtime
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
        required: true
      X-MyBring-API-Key:
        description: Your user's API key
        required: true
      Accept:
        description: Specify request format (application/json, application/xml)
        required: true
    queryParameters:
      fromcountry:
        description: Sender country code in valid ISO Alpha-2 format.
        type: string
        example: NO
        required: true
      tocountry:
        description: Receiver country code in valid ISO Alpha-2 format.
        type: string
        example: NO
        required: true
      frompostalcode:
        description: Sender country code in valid ISO Alpha-2 format.
        type: string
        example: NO
        required: true
      topostalcode:
        description: Receiver country code in valid ISO Alpha-2 format.
        type: string
        example: NO
        required: true
      addressline:
        description: Specify address. This parameter can be maximum 35 character long. It will be for Bedriftspakke and På døren only.
        type: string
        example: Testsvingen 12
        required: false
      product:
        description: List of services requested. Multiple services can be requested in a single request. Requested service can also be specified with a customer number separated with **:** (colon) as delimiter. For example CARGO:CARGO-123456
        type: string
      date:
        description: Shipping date. For service 5600 and PA_DOREN, this date cannot be set to more than current date + 10 days if numberOfAlternativeDeliveryDates > 0.
        type: string
        example: 2018-11-18
        required: false
      time:
        description: Shipping time
        type: string
        example: "12:30"
        required: false
      weight:
        description: Package weight in grams
        type: integer
        required: false
      volumeindm3:
        description: Package volume in dm3
        type: integer
        required: false
      loadingmeter:
        description: Package loading meters
        type: double
        required: false
      width:
        description: Package width in cm
        type: integer
        required: false
      length:
        description: Package length in cm
        type: integer
        required: false
      height:
        description: Package height in cm
        type: integer
        required: false
      numberofpallets:
        displayName: Number of pallets
        type: integer
        required: false
      nonstackable:
        description: Set to true if you know that pallet would be non-stackable
        type: boolean
        required: false
        default: false
      edi:
        description: Tells if the parcel will be registered using EDI when being booked. It may affect price and which services are available
        type: boolean
        required: false
        default: true
      postingatpostoffice:
        description: |
          Tells whether the parcel is delivered at a post office when it is shipped. A surcharge will be applied for SERVICEPAKKE and BPAKKE_DOR-DOR
        type: boolean
        required: false
        default: false
      additionalservice:
        displayName: Additional service
        description: Multiple value added services can be requested by repeating this parameter
        required: false
        type: string
      customernumber:
        description: Lets you specify which customer number to use in the request. If specified and service is not supplied with delimited customer number, then it will be applied on all request services. Required if `estimateddeliverytime` is set to true.
        type: string
        example: CARGO-123456
        required: false
      language:
        description: Language used for the service texts
        type: string
        default: no
        required: false
      volumeSpecial:
        description: True if the package has a shape that requires special handling
        type: boolean
        default: false
        required: false
      incoterms:
        description: Terms of delivery
        type: string
        required: false
      unnumber:
        description: Code for dangerous goods
        type: integer
        required: false
      payer:
        description: Payer type. Possible values are SENDER, RECEIVER or THIRD_PARTY
        type: string
        required: false
      numberOfAlternativeDeliveryDates:
        description: Number of alternative delivery dates to be suggested by API for request. Maximum number is 9.
        type: integer
        required: false
      nonstandardcourierservice:
        description: Specify service code for customize courier services in the request. It will be for NonStandard Courier only.
        type: string
        example: CDA
        required: true
      estimateddeliverytime:
        description: True if you want estimated delivery time of input pickup points. Eligible services are 5800 and SERVICEPAKKE.
        type: boolean
        required: false
      uniqueAlternateDeliveryDates:
        description: True if you want unique expected delivery dates when requested with `numberofdeliverydates`.
        type: boolean
        required: false
      pickuppoints:
        description: If pickup points are specified then estimated delivery time will be added in the response for them, when `estimateddeliverytime'` flag is True. If it is not specified, then default pickup point(s) for receiver's postal code will be used. Eligible services are 5800 and SERVICEPAKKE. However we recommend to always specify pickup points for optimum results.
        type: string
        example: "171102,124518"
        required: false

    responses:
      200:
        displayName: Successful response
        description: |
          Example Request \
          [https://api.bring.com/shippingguide/v2/products?fromcountry=NO&tocountry=NO&customernumber=PARCELS_NORWAY-1234567890&frompostalcode=0165&topostalcode=1234&product=5000&product=5800:PARCELS_NORWAY-1234567990&weight=200]() \
          A successful response
      400:
        displayName: User error
        description: |
          This can mean that a required field or parameter has not been provided, the value supplied is invalid, or the combination of provided fields is invalid.
      401:
        displayName: Unauthorized
        description: |
          A failed response when the request is unauthenticated

/v2/products/price:
  displayName: Get shipment prices
  description: |
      Use this endpoint to get prices. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Use this endpoint to get price. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_v2/#get-shipment-prices-and-estimated-delivery)

/v2/products/expectedDelivery:
  displayName: Get expected delivery times
  description: |
      Use this endpoint to get expected delivery. The request parameters are the same as for [Get shipment prices and estimated delivery](/api/shipping-guide_2/#get-shipment-prices-and-estimated-delivery)
  get:
    description: Get estimated delivery time

/api/ws:
  displayName: SOAP
  description: |
      The SOAP Body follows the same XML Schema Definition (XSD) as stated above.
      ### Estimated delivery times
        To get estimated delivery times in the response, set `WithExpectedDelivery` and `WithEstimatedDeliveryTime` to true in the request along with specifying `PickupPoints`
      ### Request and response structure
        If you request shipping alternatives via the API your request and response will have to comply with the following schemas:

        [https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd](https://api.bring.com/shippingguide/api/ws/shipping-guide-20.xsd)

        [https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl](https://api.bring.com/shippingguide/api/ws/shippingguide-20.wsdl)

  post:
    description: Use this endpoint to get same information as above REST API
    headers:
      X-MyBring-API-Uid:
        description: Your Mybring login ID
      X-MyBring-API-Key:
        description: Your user's API key
      Accept:
        description: Specify request format (application/xml)
    body:
      application/xml:
        examples:
          estimated_delivery_time_request:
            displayName: Estimated delivery time
            value: !include examples/soap_estimated_delivery_time_request.xml
    responses:
          200:
            displayName: Estimated delivery time successful response
            body:
              application/xml:
                examples:
                  estimated_delivery_time_response:
                    displayName: Estimated delivery time
                    value: !include examples/soap_estimated_delivery_time_response_200.xml


Added filters from version 1.0 that were not yet included in the (newly started) 2.0 raml

#%RAML 1.0
title: Digitale Delta - API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: Future enhancements and research
   content: !include documentation/dd/Future_Enhancements_and_Research.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    description: The Nodes endpoint returns the nodes that the provider offers.
    get:
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: AquaDeskPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      description: Request a specific Node by its unique dentifier.
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    description: Retrieve (data)source resources.
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        The locations endpoint returns the locations where measurements and/or model results are available.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
          example: [4.8, 52.0, 5.8, 54.0]
        locationName?:
          type: string
          description: (Partial) location name. Partial meaning startsWith(...).
          example: NEDHMT
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: string
          description: Location code.
          example: NLWATB-RWTS_AFGDM_0001
        locationId?: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON format.
        is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
            example: [4.8, 52.0, 5.8, 54.0]
          locationName?:
            type: string
            description: (Partial) location name. Partial meaning startsWith(...).
            example: NEDHMT
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: string
            description: Location code.
            example: NLWATB-RWTS_AFGDM_0001
          locationId?: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON format.
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response-geojson.json

######################################################

  /aspectSets:
    description:
      Retrieves available aspect sets.
      Note - The request requires some parameters to provide a context for the response as aspects relate to observation types for instance.
      When aspects and aspect sets are not supported and empty List shall be returned.
    get:
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError  ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.AspectSetListResponse
              example: !include examples/dd-aspectsetlist-response.json

######################################################

  /observationTypes:
    description: The ObservationTypes endpoint can return the observationtypes that the provider offers. Filtering: list of parameters.

About ObservationType

The ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.

    get:
      description: |
        Retrieve observationTypes resources.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      description: Request a specific ObservationType by its unique identifier.
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        Retrieve timeseries resources.
        A request where both startTime and endTime are omitted returns a response with just the metadata (implicit includeMetaData = true).
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: string
          example: "HVH"
        locationName?:
          type: DD-T.LocationName
          example: "Hoek.vanHolland.nieuwewat"
        sourceName?:
          type: DD-T.SourceName
          example: rws_prediction
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        quantity?:
          description: Implementation is optional. Preferably to be implemented by means of the generic filtering mechanism.
          type: string
        valueType?:
          description: Value type (float, integer, categorized).
          type: string
        nodeId?:
          type: DD-T.Identifier
        qualifier?:
          description: Filter for the optional qualifier property.
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
          description: Remark: Only required for systems that implement aspect sets
        quantityName?:
          type: DD-T.QuantityName
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
        intervalLength?:
          type: DD-T.IntervalLength
          description: Remark: Only required for systems that are accessed by RWS's MKK-DL
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      description: Request a specific (single) Timeseries by its unique identifier.
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json

#%RAML 1.0
title: Digitale Delta - API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication
  openidconnect:
    type: OAuth 2.0
baseUri: http://api.rws.nl/dl/
mediaType: [ application/json ]
description: Digital Delta API version 2.0
documentation:
 - title: Introduction
   content: !include documentation/dd/Introduction.md
 - title: Document history
   content: !include documentation/dd/Document_History.md
 - title: The API specification
   content: !include documentation/dd/The_API_Specification.md
 - title: Future enhancements and research
   content: !include documentation/dd/Future_Enhancements_and_Research.md

# HTTP is included as protocol but is optional as for security reasons a Provider might decide to support HTTPS only.
protocols:
  - HTTP
  - HTTPS

uses:
  DD-T: libraries/dd-base-types.raml
  GENERIC-RESP: libraries/generic-response-types.raml
  DD-RESP: libraries/dd-response-types.raml
  TRAITS: libraries/dd-traits.raml

#
# All data types are defined in external files (see above) so they can be shared between DD and DD-OPER API.
#
types:

#
# The resources
/dd/2.0:

# ##################################################

  /nodes:
    description: The Nodes endpoint returns the nodes that the provider offers.
    get:
      is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        name?:
          type: string
          description: (Partial) name of the node. Partial meaning startsWith(...).
          example: AquaDeskPrimaryNode
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.NodeListResponse
              example: !include examples/dd-nodelist-response.json
    /{nodeId}:
      description: Request a specific Node by its unique dentifier.
      uriParameters:
        nodeId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.NodeResponse
                example: !include examples/dd-node-response.json

# ##################################################

  /sources:
    description: Retrieve (data)source resources.
    is: [ TRAITS.pageable, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError ]
    get:
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.SourceListResponse
              example: !include examples/dd-sourcelist-response.json

# #####################################################

  /locations:
    get:
      description: |
        The locations endpoint returns the locations where measurements and/or model results are available.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        boundingBox?:
          type: DD-T.BoundingBox
          example: [4.8, 52.0, 5.8, 54.0]
        locationName?:
          type: string
          description: (Partial) location name. Partial meaning startsWith(...).
          example: NEDHMT
        nodeId?:
          type: DD-T.Identifier
          description: This query parameter is deprecated.
        locationCode?:
          type: string
          description: Location code.
          example: NLWATB-RWTS_AFGDM_0001
        locationId?: DD-T.Identifier
      responses:
        200:
          description: Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.LocationListResponse
              example: !include examples/dd-locationslist-response.json

    /geojson:
      get:
        description: |
          Retrieve location resources. Response is in GeoJSON format.
        is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.locationFilterable ]
        queryParameters:
          process?:
            type: DD-T.ProcessName
          boundingBox?:
            type: DD-T.BoundingBox
            example: [4.8, 52.0, 5.8, 54.0]
          locationName?:
            type: string
            description: (Partial) location name. Partial meaning startsWith(...).
            example: NEDHMT
          nodeId?:
            type: DD-T.Identifier
            description: This query parameter is deprecated.
          locationCode?:
            type: string
            description: Location code.
            example: NLWATB-RWTS_AFGDM_0001
          locationId?: DD-T.Identifier
        responses:
          200:
            description: Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.LocationListResponseGeoJSON
                example: !include examples/dd-locationslist-response-geojson.json

    /{locationId}:
      description: Request a specific location by its id. Response is always in GeoJSON format.
      uriParameters:
        locationId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        description: |
          Request a specific Location by its unique dentifier.
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: object
                example: !include examples/dd-location-response-geojson.json

######################################################

  /aspectSets:
    description:
      Retrieves available aspect sets.
      Note - The request requires some parameters to provide a context for the response as aspects relate to observation types for instance.
      When aspects and aspect sets are not supported and empty List shall be returned.
    get:
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError  ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
      responses:
        200:
          description: |
            Succesfully retrieved resource.
          body:
            application/json:
              type: DD-RESP.AspectSetListResponse
              example: !include examples/dd-aspectsetlist-response.json

######################################################

  /observationTypes:
    description: The ObservationTypes endpoint can return the observationtypes that the provider offers. Filtering: list of parameters.

About ObservationType

The ObservationType objects describe all attributes to correctly interpret what has been measured, and in what way. It is essential to have the quantity field.

    get:
      description: |
        Retrieve observationTypes resources.
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        observationTypeId?:
          type: DD-T.Identifier
        quantity?:
          description: Retrieve only observation types that contain the specified quantity.
          type: string
        parameterCode?:
          description: Retrieve only observation types that contain the specified parameter code.
          type: string
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.ObservationTypeListResponse
              example: !include examples/dd-observationtypelist-response.json

    /{observationTypeId}:
      description: Request a specific ObservationType by its unique identifier.
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      uriParameters:
        observationTypeId:
          type: DD-T.Identifier
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
        responses:
          200:
            description: |
              Succesfully retrieved resource.
            body:
              application/json:
                type: DD-RESP.ObservationTypeResponse
                example: !include examples/dd-observationtype-response.json

######################################################

  /timeseries:
    get:
      description: |
        Retrieve timeseries resources.
        A request where both startTime and endTime are omitted returns a response with just the metadata (implicit includeMetaData = true).
      is: [ TRAITS.pageable, TRAITS.has400-InvalidRequestError, TRAITS.has403-AccessDeniedError, TRAITS.has500-ServerError, TRAITS.timeseriesFilterable, TRAITS.locationFilterable, TRAITS.observationTypeFilterable ]
      queryParameters:
        process?:
          type: DD-T.ProcessName
        startTime?:
          type: DD-T.StartTime
        endTime?:
          type: DD-T.EndTime
        locationCode?:
          type: string
          example: "HVH"
        locationName?:
          type: DD-T.LocationName
          example: "Hoek.vanHolland.nieuwewat"
        sourceName:
          type: DD-T.SourceName
          example: rws_prediction
        observationTypeId?:
          type: DD-T.Identifier
        realizationCount?:
          description: Added Count as this is the name in ObservationType response.
          type: integer
        parameterCode?:
          type: string
        quantity?:
          description:
          type: string
        aspectSet?:
          type: DD-T.AspectSetName
        quantityName?:
          type: DD-T.QuantityName
        intervalLength?:
          type: DD-T.IntervalLength
        nodeId?:
          type: DD-T.Identifier
      responses:
        200:
          description: |
            Succesfully retrieved timeseries.
          body:
            application/json:
              type: DD-RESP.TimeseriesListResponse
              example: !include examples/dd-timeserieslist-response-verwachtingen-en-metingen-fulldd.json

    /{timeseriesId}:
      description: Request a specific (single) Timeseries by its unique identifier.
      uriParameters:
        timeseriesId:
          type: DD-T.Identifier
      is: [ TRAITS.has403-AccessDeniedError, TRAITS.has404-NotFoundError, TRAITS.has500-ServerError ]
      get:
        queryParameters:
          process?:
            type: DD-T.ProcessName
            default: measurement
        responses:
          200:
            description: |
              Succesfully retrieved resource
            body:
              application/json:
                type: DD-RESP.TimeseriesResponse
                example: !include examples/dd-timeseries-response-single.json