Change host port type  to ephemeral port number (#4820)

Adjust the network host port type from `numbers.Port` to
`numbers.EphemeralPort` to properly document the allowed value range.
This change aligns `network` with `appContainer`.

Fixes #4817

#%RAML 1.0 Library
uses:
  label: label.raml
  numbers: numberTypes.raml
  strings: stringTypes.raml
types:
  Endpoint:
    type: object
    description: |
      Endpoints accept connections from outside of a pod.
      Endpoints may also be advertised outside of a cluster.
    properties:
      name:
        type: strings.Name
        description: |
          Name of this port. Should be unique in the context of the pod.
      containerPort?:
        type: numbers.Port
        description: |
          The container port that a task's process is actually listening on.
          Required if the network mode is container
      hostPort?:
        type: numbers.EphemeralPort
        description: |
          Mapped port on the host.
          All host ports are allocated from resource offers.
        usage: Specify 0 to tell Marathon to dynamically allocate a host port.
      protocol?:
        type: array
        items: strings.Name
        minItems: 1
        description: |
          The protocol of this port, advertised in Mesos DiscoveryInfo (DI).
          Specifying more than one protocol here will result in the generation
          of multiple Port DI entries.
      labels?:
        type: label.KVLabels
        description: |
          Metadata as key/value pair. Possible uses include VIPs,
          per-network-interface binding

  NetworkMode:
    type: string
    enum: [container, host]
  Network:
    type: object
    properties:
      name?:
        type: strings.Name
        description: |
          Defines the name of the container network to join.
          Not for use with `host` mode networking.
      mode?:
        type: NetworkMode
        default: container
      labels?:
        type: label.KVLabels
        description: |
          Labels applied to the pod's NetworkInfo.
          Ignored when using `host` node networking.
  IpDiscoveryPort:
    type: object
    description: Port
    properties:
      number:
        type: integer
        format: int32
        minimum: 0
        maximum: 65535
        description: The port number
      name:
        type: string
        description: Name of the port
        pattern: ^[a-z][a-z0-9-]*$
      protocol: strings.NetworkProtocol
  IpDiscovery:
    type: object
    description: Information useful for service discovery
    properties:
      ports?:
        type: IpDiscoveryPort[]
        description: |
          Array of objects describing the ports exposed by each task
  IpAddress:
    type: object
    description: |
      If an application definition includes the 'ipAddress' field, then Marathon
      will request a per-task IP from Mesos.
      A separate ports/portMappings configuration is then disallowed.
    properties:
      discovery?:
        type: IpDiscovery
        description: |
          DEPRECATED. Please try to use portMappings instead.
      groups?:
        type: array
        description: |
          DEPRECATED. Will be ignored in a future release.
          Array of network groups.
          One IP address can belong to zero or more network groups.
          The idea is that containers can only reach containers with which they
          share at least one network group.
        items: string
      labels?: label.KVLabels
      networkName?:
        type: string
        description: |
          If present, declares the name of the network that the container should
          join.
          In practice it is up to the IPAM to decide how to interpret this field
  PortDefinition:
    type: object
    properties:
      port?:
        type: integer
        format: int32
        default: 0
        description: |
          if requirePorts is set to true, then this port number will be used
          on the agent host Otherwise if the requirePorts is set to false and
          this port number is not zero, then it will be used as a service port
          and a dynamic port will be used on the agent host.
          If it is set to zero, a dynamic port will be used on the host and a
          unique service port will be assigned by Marathon.
      labels?: label.KVLabels
      name?:
        type: string
        description: |
          Name of the service hosted on this port.
          If provided, it must be unique over all port definitions.
        pattern: ^[a-z][a-z0-90]*$
      protocol?:
        type: strings.NetworkProtocol
        default: tcp
        description: If this port is used for tcp or udp or both.

#%RAML 1.0 Library
uses:
  label: label.raml
  numbers: numberTypes.raml
  strings: stringTypes.raml
types:
  Endpoint:
    type: object
    description: |
      Endpoints accept connections from outside of a pod.
      Endpoints may also be advertised outside of a cluster.
    properties:
      name:
        type: strings.Name
        description: |
          Name of this port. Should be unique in the context of the pod.
      containerPort?:
        type: numbers.Port
        description: |
          The container port that a task's process is actually listening on.
          Required if the network mode is container
      hostPort?:
        type: numbers.Port
        description: |
          Mapped port on the host.
          All host ports are allocated from resource offers.
        usage: Specify 0 to tell Marathon to dynamically allocate a host port.
        minimum: 0
      protocol?:
        type: array
        items: strings.Name
        minItems: 1
        description: |
          The protocol of this port, advertised in Mesos DiscoveryInfo (DI).
          Specifying more than one protocol here will result in the generation
          of multiple Port DI entries.
      labels?:
        type: label.KVLabels
        description: |
          Metadata as key/value pair. Possible uses include VIPs,
          per-network-interface binding

  NetworkMode:
    type: string
    enum: [container, host]
  Network:
    type: object
    properties:
      name?:
        type: strings.Name
        description: |
          Defines the name of the container network to join.
          Not for use with `host` mode networking.
      mode?:
        type: NetworkMode
        default: container
      labels?:
        type: label.KVLabels
        description: |
          Labels applied to the pod's NetworkInfo.
          Ignored when using `host` node networking.
  IpDiscoveryPort:
    type: object
    description: Port
    properties:
      number:
        type: integer
        format: int32
        minimum: 0
        maximum: 65535
        description: The port number
      name:
        type: string
        description: Name of the port
        pattern: ^[a-z][a-z0-9-]*$
      protocol: strings.NetworkProtocol
  IpDiscovery:
    type: object
    description: Information useful for service discovery
    properties:
      ports?:
        type: IpDiscoveryPort[]
        description: |
          Array of objects describing the ports exposed by each task
  IpAddress:
    type: object
    description: |
      If an application definition includes the 'ipAddress' field, then Marathon
      will request a per-task IP from Mesos.
      A separate ports/portMappings configuration is then disallowed.
    properties:
      discovery?:
        type: IpDiscovery
        description: |
          DEPRECATED. Please try to use portMappings instead.
      groups?:
        type: array
        description: |
          DEPRECATED. Will be ignored in a future release.
          Array of network groups.
          One IP address can belong to zero or more network groups.
          The idea is that containers can only reach containers with which they
          share at least one network group.
        items: string
      labels?: label.KVLabels
      networkName?:
        type: string
        description: |
          If present, declares the name of the network that the container should
          join.
          In practice it is up to the IPAM to decide how to interpret this field
  PortDefinition:
    type: object
    properties:
      port?:
        type: integer
        format: int32
        default: 0
        description: |
          if requirePorts is set to true, then this port number will be used
          on the agent host Otherwise if the requirePorts is set to false and
          this port number is not zero, then it will be used as a service port
          and a dynamic port will be used on the agent host.
          If it is set to zero, a dynamic port will be used on the host and a
          unique service port will be assigned by Marathon.
      labels?: label.KVLabels
      name?:
        type: string
        description: |
          Name of the service hosted on this port.
          If provided, it must be unique over all port definitions.
        pattern: ^[a-z][a-z0-90]*$
      protocol?:
        type: strings.NetworkProtocol
        default: tcp
        description: If this port is used for tcp or udp or both.


Update descriptions

Update descriptions

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "orders"
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

documentation:
- title: Introduction
  content: |
      This API is for ordering [Pakke i postkassen](http://www.bring.no/sende/pakker/private-i-norge/pakke-i-postkassen) (Mailbox Delivery) shipments.

      The Mailbox Delivery service is available domestically in Norway, and will replace "Minipakke" and "Småpakker".

- title: Tracking with RFID
  content: |
      Mailbox Delivery shipments can optionally be ordered with tracking using RFID.

      #### How does tracking with RFID work?

      Normally, we create PDF labels that can be printed on any printer.

      If you opt for tracking, we create ZPL labels instead. ZPL stands for [Zebra Programming Language (ZPL)](https://en.wikipedia.org/wiki/Zebra_(programming_language)).

      The labels will be ZPL code containing instructions for programming the passive RFID antenna in the printer's labels with package numbers.

      In addition to the RFID programming instructions, the ZPL code contains instructions for rendering the rest of the label (addresses, icons, barcode, etc.).

      #### Special hardware required

      RFID-tagged labels require special printer hardware. Currently we support the following printers:

      - Zebra R410
      - Zebra 500R

- title: Without tracking
  content: |
      If you don't have a supported printer, you cannot order shipments with tracking. In this case, we will create normal PDF labels that can be printed using any printer.

- title: Authentication
  content: |
    The API requires authentication for all its endpoints. 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 |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

/:
  displayName: Order shipment
  description: |
      Order (or validate) a shipment.

      #### New endpoint coming

      Currently, we have only one endpoint for ordering shipments. This
      endpoint requires all packages in the shipment to be ordered at once. We
      are working on a new endpoint that can be used for generating labels before
      placing the order. This will allow you to stick labels on packages so they're
      ready to be sent, then later place an order to get a waybill.

      #### Error codes

      From the [JSON API specification](http://jsonapi.org/format/#error-objects),
      we use `code`, `title`, and `source.pointer` to describe errors.

      | Code | Meaning | Example pointer |
      | 500 | Internal, unknown aplpication error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 3000 | Invalid email address | `/packages/0/email` |
      | 4000 | Invalid postal code |  `/packages/1/postalCode` |
      | 5000 | User does not have access to customer number | `/customerNumber` |
      | 5500 | Customer hasn't made agreement with Posten to send "Pakke i postkassen" | `/customerNumber` |
      | 6000 | Weight cannot be more than 2000 grams | `/packages/2/weight` |
      | 7000 | Priority must be A or B | `/packages/3/priority` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        examples:
          with_tracking:
            displayName: With tracking
            value: !include examples/with_tracking_request.json
          without_tracking:
            displayName: Without tracking
            value: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        description: The API returns 200 when validating the request by specifying query parameter `validate=true`.
        body:
          application/json:
            type: ValidatedOrderResponse
            examples:
              valid_order:
                displayName: Valid order
                value: !include examples/validate_order_response.json
      201:
        description: |
          On a successful order, the response gives information about the shipment.
          Most importantly it contains a links to labels and waybill that have to
          be printed and sent with the shipment:

          - `labelUri`: PDF for packages without tracking
          - `rfidLabelUri`: ZPL for packages with tracking
          - `waybillUri`: PDF for the shipment's waybill
        body:
          application/json:
            type: SuccessfulOrderResponse
            examples:
              with_tracking:
                displayName: With tracking
                value: !include examples/with_tracking_response.json
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
      422:
        description: |
          When the request contained invalid data, we return a 422 with a list
          of errors for the shipment.
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Returns the same object that was returned when placing the order.
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json

#%RAML 1.0
---
title: Order to Mailbox API
version: v1
baseUri: https://api.bring.com/order/to-mailbox
mediaType: application/json
annotationTypes:
  hideInDocumentation: boolean
  hideRequired: boolean
types:
  Order:
    type: object
    description: An order to place in Mybring.
    properties:
      customerNumber:
        type: string
        description: API customer number for which to place the order.
      senderName:
        type: string
        description: Sender's name.
        example: Min Bedrift
      senderEmail:
        required: false
        type: string
        pattern: ".+@.+"
        description: Sender's email address. Defaults to the user's email address.
      postalCode:
        type: string
        description: Sender's postal code. Must be a valid Norwegian postal code.
      streetAddress:
        type: string
        description: Sender's street address.
      reference:
        required: true
        description: A reference for the shipment (all packages).
      packages:
        minItems: 1
        type: Package[]
        description: The packages to send in this shipment.
  Package:
    type: object
    description: A single package in a shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to activate [tracking with RFID](#tracking-with-rfid) for the package.
      weight:
        maximum: 2000
        type: integer
        description: Weight in grams.
      recipientName:
        type: string
        description: Recipient name.
      postalCode:
        type: string
        description: A valid Norwegian postal code.
      streetAddress:
        type: string
        description: Recipient's street address.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number, including country code.
        example: "+4700000000"
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
  SuccessfulOrder:
    (hideRequired): true
    displayName: Successful Order
    description: A successfully placed order that contains links to labels and waybill.
    properties:
      id:
        type: number
        description: The ID of the order that was placed.
      customerNumber:
        type: string
        description: The API customer number for which the order was placed.
      customerName:
        type: string
        description: The name of the customer for which the order was placed.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for which the order was placed.
      senderName:
        type: string
        description: Sender's name.
      streetAddress:
        type: string
        description: Sender's street address.
      postalCode:
        type: string
        description: Sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        pattern: ".+@.+"
        description: Sender's email address that for the order that was placed.
      reference:
        type: string
        description: A reference for the shipment (all packages)
      labelUri:
        type: string
        description: URL to PDF label(s) for packages ordered without tracking.
      rfidLabelUri:
        type: string
        description: URL to ZPL label(s) for packages ordered with tracking.
      waybillUri:
        type: string
        description: URL to waybill PDF that has to be printed and sent with the shipment.
      orderNumberReference:
        type: string
        description: The order number reference for the placed order. This is the number on the waybill.
      priceWithoutVat:
        type: number
        description: Price of shipment without VAT (MVA).
      priceWithVat:
        type: number
        description: Price of shipment with VAT (MVA).
      vat:
        type: number
        description: How much of the price was VAT (MVA).
      currency:
        type: string
        default: NOK
        description: The currency for the price.
      orderTime:
        type: datetime
        example: 2017-09-01T14:00:00.000Z
        description: Timestamp for when the order was placed.
      userEmail:
        required: false
        type: string
        description: The email address for the user that placed the order.
      userPhone:
        required: false
        type: string
        description: The phone number for the user that placed the order.
      userFullName:
        required: false
        type: string
        description: The name for the user that placed the order.
      packages:
        minItems: 1
        description: Packages in this shipment.
        type: OrderedPackage[]
  OrderedPackage:
    (hideRequired): true
    displayName: Ordered Package
    description: A single package in a successfully ordered shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking for the package](#tracking-with-rfid) was activated.
      specialist:
        type: string
        description: The type of customer for which the order was placed.
      recipientName:
        type: string
        description: Recipient name.
      streetAddress:
        type: string
        description: Recipient's street address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        pattern: "\\+[0-9 ]+"
        description: Recipient's phone number.
      email:
        type: string
        pattern: ".+@.+"
        description: Recipient's email address.
      weight:
        maximum: 2000
        type: integer
        description: Package weight in grams.
      shipmentNumber:
        type: string
        description: The shipment number for this package. A package in a PIP shipment will have both a shipment number and a package number.
      packageNumber:
        type: string
        description: The package number for this package. This goes on the label.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  ValidatedOrder:
    (hideRequired): true
    displayName: Validated Order
    description: A valid order that can be placed.
    properties:
      customerNumber:
        type: string
        description: The API customer number for the validated order.
      customerName:
        type: string
        description: The name of the customer for the validated order.
      customerOrganizationNumber:
        type: string
        description: The organization number of the customer for the validated order.
      senderName:
        type: string
        description: The sender's name.
      streetAddress:
        type: string
        description: The sender's street address.
      postalCode:
        type: string
        description: The sender's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      email:
        type: string
        description: The sender's email address.
      reference:
        type: string
        description: A reference for the shipment (all packages).
      priceWithoutVat:
        type: number
        description: Calculated price without VAT (MVA).
      priceWithVat:
        type: number
        description: Calulated price with VAT (MVA).
      vat:
        type: number
        description: Calculated VAT (MVA).
      currency:
        type: string
        description: The price's currency.
      orderTime:
        type: datetime
        description: Timestamp for when the order was validated.
      packages:
        minItems: 1
        description: Packages in this validated shipment.
        type: ValidatedPackage[]
  ValidatedPackage:
    (hideRequired): true
    displayName: Validated Package
    description: A single, valid package in a valid shipment.
    properties:
      priority:
        enum: [ A, B ]
        description: Delivery speed (A-post or B-post).
      rfid:
        type: boolean
        description: Whether to [tracking with RFID](#tracking-with-rfid) was activated for the package.
      recipientName:
        type: string
        description: Recipient's name.
      streetAddress:
        type: string
        description: Recipient's email address.
      postalCode:
        type: string
        description: Recipient's postal code.
      postalPlace:
        type: string
        description: The city/place for the postal code.
      phoneNumber:
        type: string
        description: Recipient's phone number.
      email:
        type: string
        description: Recipient's email address.
      weight:
        type: integer
        description: Package weight in grams.
      agreementNumber:
        type: boolean
        description: Whether the customer has an agreement price for this package.
  OrderRequest:
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "orders"
            description: JSON-API type.
          attributes:
            type: Order
            description: Order properties.
  SuccessfulOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            description: JSON-API type.
          id: string
          attributes:
            type: SuccessfulOrder
            description: Order properties.
  ValidatedOrderResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      data:
        type: object
        description: JSON-API data object.
        properties:
          type:
            type: string
            pattern: "order"
            description: JSON-API type.
          attributes:
            type: ValidatedOrder
            description: Order properties.
  ErrorResponse:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      errors:
        type: ErrorObject[]
        description: See the [JSON-API documentation](http://jsonapi.org/format/#error-objects).
  ErrorObject:
    (hideRequired): true
    (hideInDocumentation): true
    type: object
    properties:
      code:
        type: string
        description: Machine-readable description of error.
      title:
        type: string
        description: Human-readable description of error.
      source:
        type: object
        properties:
          pointer:
            type: string
            description: A JSON pointer to the associated entity of

documentation:
- title: Introduction
  content: |
      This API is for ordering [Pakke i postkassen](http://www.bring.no/sende/pakker/private-i-norge/pakke-i-postkassen) (Mailbox Delivery) shipments.

      The Mailbox Delivery service is available domestically in Norway, and will replace "Minipakke" and "Småpakker".

- title: Tracking with RFID
  content: |
      Mailbox Delivery shipments can optionally be ordered with tracking using RFID.

      #### How does tracking with RFID work?

      Normally, we create PDF labels that can be printed on any printer.

      If you opt for tracking, we create ZPL labels instead. ZPL stands for [Zebra Programming Language (ZPL)](https://en.wikipedia.org/wiki/Zebra_(programming_language)).

      The labels will be ZPL code containing instructions for programming the passive RFID antenna in the printer's labels with package numbers.

      In addition to the RFID programming instructions, the ZPL code contains instructions for rendering the rest of the label (addresses, icons, barcode, etc.).

      #### Special hardware required

      RFID-tagged labels require special printer hardware. Currently we support the following printers:

      - Zebra R410
      - Zebra 500R

- title: Without tracking
  content: |
      If you don't have a supported printer, you cannot order shipments with tracking. In this case, we will create normal PDF labels that can be printed using any printer.

- title: Authentication
  content: |
    The API requires authentication for all its endpoints. 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 |

    Those headers must be present for authenticating requests.

- title: JSON API
  content: |
      This API adheres to the [JSON API](http://jsonapi.org/) specification.

/:
  displayName: Order shipment
  description: |
      Order (or validate) a shipment.

      #### Error codes

      From the [JSON API specification](http://jsonapi.org/format/#error-objects),
      we use `code`, `title`, and `source.pointer` to describe errors.

      | Code | Meaning | Example pointer |
      | 500 | Internal, unknown aplpication error | `/` |
      | 1000 | Missing field value | `/streetAddress` |
      | 2000 | Order must contain at least one package | `/packages` |
      | 3000 | Invalid email address | `/packages/0/email` |
      | 4000 | Invalid postal code |  `/packages/1/postalCode` |
      | 5000 | User does not have access to customer number | `/customerNumber` |
      | 5500 | Customer hasn't made agreement with Posten to send "Pakke i postkassen" | `/customerNumber` |
      | 6000 | Weight cannot be more than 2000 grams | `/packages/2/weight` |
      | 7000 | Priority must be A or B | `/packages/3/priority` |
      | 8000 | Invalid phone number | `/pacakges/4/phoneNumber` |
      | 9000 | Invalid JSON API resource type (must be `orders`) | `/data/type` |

  post:
    description: Order shipment
    headers:
      Content-Type:
        description: Specify request format (application/json)
        required: true
        enum: [ application/json ]
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    queryParameters:
        validate:
            description: If this is set to true, the order will only be validated, not ordered in our production systems.
            type: boolean
            required: false
    body:
      application/json:
        examples:
          with_tracking:
            displayName: With tracking
            value: !include examples/with_tracking_request.json
          without_tracking:
            displayName: Without tracking
            value: !include examples/without_tracking_request.json
        type: OrderRequest
    responses:
      200:
        description: The API returns 200 when validating the request by specifying query parameter `validate=true`.
        body:
          application/json:
            type: ValidatedOrderResponse
            examples:
              valid_order:
                displayName: Valid order
                value: !include examples/validate_order_response.json
      201:
        description: On a successful request, the response gives information about the booking. Most importantly it contains a link to the label for the shipment.
        body:
          application/json:
            type: SuccessfulOrderResponse
            examples:
              with_tracking:
                displayName: With tracking
                value: !include examples/with_tracking_response.json
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json
      422:
        description: Validation error
        body:
          application/json:
            type: ErrorResponse
            examples:
              invalid_order:
                displayName: Invalid order
                value: !include examples/422.json
      500:
        description: If we have an error in our backend, we'll return a 500 error.
        body:
          application/json:
            type: ErrorResponse
            examples:
              server_error:
                displayName: Server error
                value: !include examples/500.json

/{orderId}:
  displayName: Fetch order
  uriParameters:
    orderId:
      type: string
      description: Id from when placing an order.
  get:
    description: Fetch previously ordered shipment
    headers:
      Accept:
        description: Specify response format (application/json)
        required: true
        enum: [ application/json ]
    responses:
      200:
        description: Success!!!!
        body:
          application/json:
            displayName: JSON response
            description: A response in the form of application/json
            type: SuccessfulOrderResponse
            examples:
              without_tracking:
                displayName: Without tracking
                value: !include examples/without_tracking_response.json


Add semester periods example to RAML

Add semester periods example to RAML

#%RAML 0.8
title: CTU Sirius API
version: v1
baseUri: https://sirius.fit.cvut.cz/api/{version}
securedBy: [access_token]
securitySchemes:
  - access_token:
      description: |
        All Sirius read-only resources are secured by an access token. The token is either
        associated with an username (personal) or is set as global. This authorization
        scheme uses the same query parameter as OAuth 2.0, and will be later
        replaced by OAuth 2.0.
      type: x-access-token
      describedBy:
        queryParameters:
          access_token:
            description: |
              Used to send a valid access token.
            type: string
        responses:
          401:
            description: |
              Missing or invalid token. Authorization token was not specified or is not valid.
traits:
  - paged:
      usage: Retreive further pages in collection
      description: Use `offset` and `limit` to paginate the records.
      queryParameters:
        limit:
          description: The number of entries in collection to return
          type: number
          default: 10
          maximum: 100
        offset:
          description: Offset of the first entry in collection
          type: number
          default: 0
  - dateScoped:
      queryParameters:
        from:
          description: Return events from this date
          type: date
        to:
          description: Return events up to this date
          type: date
        with_original_date:
          description: >
            When the date of event has been changed by a schedule exception, original date is not
            considered for date filtering (by from/to parameters). With this parameter Sirius will
            include events’ original date in a date filter.
          type: boolean
          default: false
  - deletable:
      queryParameters:
        deleted:
          description: Return even events that have been deleted.
          type: boolean
          default: false
  - filterable:
      queryParameters:
        event_type:
          description: Filter by event's type
          type: string
          enum: [ assessment, course_event, exam, laboratory, lecture, tutorial ]
  - includable:
      description: >
        Includes the specified linked resources into the response (similar to compound documents
        in the JSON API format).
      queryParameters:
        include:
          description: A comma-separated list of the link names to include.
          type: string
          example: courses,teachers,schedule_exceptions
  - secured:
      description: Marks resource as secured. You need to be authenticated and authorized to access it.
      queryParameters:
        access_token:
          description: Authentication and authorization is required. You need to set your `access_token` in URL.
          type: string
          example: 07a855e0-6920-11e4-a40a-0002a5d5c51b
          required: true
resourceTypes:
  - events-collection:
      get:
        is: [ dateScoped, deletable, filterable, includable, paged, secured ]
        responses:
          200:
            body:
              application/json:
                example: |
                    {
                      "meta": {
                        "count": 2,
                        "offset": 0,
                        "limit": 20
                      },
                      "events": [
                        {
                          "id": 42,
                          "name": null,
                          "sequence_number": 12,
                          "starts_at": "2014-04-23T09:15:00.000+02:00",
                          "ends_at": "2014-04-23T10:45:00.000+02:00",
                          "deleted" : false,
                          "capacity": 24,
                          "event_type": "tutorial",
                          "parallel": "106",
                          "original_data": {
                            "starts_at": "2014-04-23T09:00:00.000+02:00",
                            "ends_at": "2014-04-23T10:30:00.000+02:00",
                            "room_id": "T9:111"
                          },
                          "links": {
                            "room": "T9:350",
                            "course": "MI-RUB",
                            "teachers": [
                              "skocdopet"
                            ],
                            "students": [
                              "szolatib",
                              "vomackar"
                            ],
                            "applied_exceptions": [ 10, 15 ]
                          }
                        },
                        {
                          "id": 43,
                          "name": null,
                          "sequence_number": 12,
                          "starts_at": "2014-04-24T09:15:00.000+02:00",
                          "ends_at": "2014-04-24T10:45:00.000+02:00",
                          "deleted" : false,
                          "capacity": 196,
                          "event_type": "lecture",
                          "parallel": "1",
                          "original_data": {},
                          "links": {
                            "room": "T9:155",
                            "course": "MI-W20",
                            "teachers": [
                              "kuchajar",
                              "vitvatom"
                            ],
                            "students": [
                              "jirutjak"
                            ]
                          }
                        }
                      ]
                    }
              text/calendar:
                example: |
                  BEGIN:VCALENDAR
                  VERSION:2.0
                  CALSCALE:GREGORIAN
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/123
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/125
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  END:VCALENDAR
          404:
            description: There are no events within the current scope
  - event:
      get:
        is: [ secured ]
        responses:
          200:
            body:
              application/json:
                example: |
                  {
                    "events": {
                      "id": 42,
                      "name": null,
                      "sequence_number": 12,
                      "starts_at": "2014-04-23T07:30:00.000+02:00",
                      "ends_at": "2014-04-23T11:00:00.000+02:00",
                      "deleted" : false,
                      "capacity": 24,
                      "event_type": "tutorial",
                      "parallel": "106",
                      "original_data": {
                        "starts_at": "2014-04-23T09:00:00.000+02:00",
                        "ends_at": "2014-04-23T10:30:00.000+02:00",
                        "room_id": "T9:111"
                      },
                      "links": {
                        "room": "T9:350",
                        "course": "MI-RUB",
                        "teachers": [
                          "skocdopet"
                        ],
                        "students": [
                          "szolatib",
                          "vomackar"
                        ],
                        "applied_exceptions": [ 10, 15 ]
                      }
                    }
                  }
              text/calendar:
                example: |
                  BEGIN:VCALENDAR
                  VERSION:2.0
                  CALSCALE:GREGORIAN
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/123
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  END:VCALENDAR
/events:
  type: events-collection
  get:
    description: "Get all events without any scope"
  /{eventId}:
    type: event
/people/{username}/events:
  type: events-collection
  description: Get a calendar for a person
  uriParameters:
    username:
      description: person's unique username
      required: true
      pattern: "[a-z0-9]{3,8}"
      example: vomackar
/rooms/{kosId}/events:
  type: events-collection
  description: Get a calendar for a room
  uriParameters:
    kosId:
      description: |
        Common room identification used by KOS, for details see [the documentation](https://rozvoj.fit.cvut.cz/Main/znaceni-mistnosti#HKOSEDzna10DenED-102).
      required: true
      pattern: "[A-Z0-9]{2}:([A-Z0-9]+-)?[a-z0-9]+"
      example: "TH:A-1333"
/courses/{courseCode}/events:
  type: events-collection
  description: Get events instances for a given course
  uriParameters:
    courseCode:
      description: |
        Course code, faculty specific.
      required: true
      example: BI-PA1
/schedule_exceptions:
  description: Manage schedule exceptions
  is: [ paged ]
  get:
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "schedule_exceptions": [
                  {
                    "id": 1,
                    "type": "CANCEL",
                    "name": "Den české státnosti",
                    "scope": {
                      "starts_at": "2014-09-28T00:00:00.000+02:00",
                      "ends_at": "2014-09-29T00:00:00.000+02:00",
                      "faculty": null,
                      "semester": null,
                      "courses": null,
                      "timetable_slots": null
                    }
                  },
                  {
                    "id": 11,
                    "type": "CANCEL"
                    "name": "Děkanský den FIT",
                    "note": "Výuka odpadá",
                    "scope": {
                      "starts_at": "2015-04-30T00:00:00Z",
                      "ends_at": "2015-05-01T00:00:00Z",
                      "faculty": 18000,
                      "semester": "B142",
                      "courses": null,
                      "timetable_slots": null
                    }
                  }
                ],
                "meta": {
                  "count": 2,
                  "offset": 0,
                  "limit": 20
                }
              }
  /{id}:
    uriParameters:
      id:
        description: ID of the schedule exception
        required: true
    get:
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "schedule_exceptions": {
                    "id": 7,
                    "type": "ROOM_CHANGE",
                    "name": "MI-MPI - přednáška 24. 9. 2014 přesunuta do T9:105",
                    "scope": {
                      "starts_at": "2014-09-24T00:00:00.000+02:00",
                      "ends_at": "2014-09-25T00:00:00.000+02:00",
                      "faculty": 18000,
                      "semester": "B141",
                      "courses": null,
                      "timetable_slots": [ 392651000 ]
                    },
                    "options": {
                      "room_id": "T9:105"
                    }
                  }
                }
/semesters:
  is: [ paged, secured ]
  get:
    description: Get all semesters per faculties.
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "semesters": [
                  {
                    "id": "18000-B142",
                    "semester": "B142",
                    "faculty": 18000,
                    "starts_at": "2015-02-16",
                    "ends_at": "2015-09-21",
                    "exams_start_at": "2015-05-18",
                    "exams_end_at": "2015-06-27",
                    "teaching_ends_at": "2015-05-16",
                    "first_week_parity": "even",
                    "hour_duration": 45,
                    "hour_starts": [
                      "07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
                      "12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
                      "18:00", "18:45", "19:45"
                    ]
                  }
                ],
                "meta": {
                  "count": 4,
                  "offset": 0,
                  "limit": 1
                }
              }
  /{faculty_semester}:
    is: [ secured ]
    uriParameters:
      faculty_semester:
        description: Faculty code and semester code connected with a dash.
        pattern: "[0-9]{5}-[AB][0-9]{2}[12]"
        example: 18000-B142
        required: true
    get:
      description: Get a semester on a faculty.
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "semesters": {
                    "id": "18000-B142",
                    "semester": "B142",
                    "faculty": 18000,
                    "starts_at": "2015-02-16",
                    "ends_at": "2015-09-21",
                    "exams_start_at": "2015-05-18",
                    "exams_end_at": "2015-06-27",
                    "teaching_ends_at": "2015-05-16",
                    "first_week_parity": "even",
                    "hour_duration": 45,
                    "hour_starts": [
                      "07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
                      "12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
                      "18:00", "18:45", "19:45"
                    ],
                    "periods": [
                      {
                        "type": "teaching",
                        "starts_at": "2015-02-16",
                        "ends_at": "2015-05-16",
                        "first_week_parity": "even"
                      },
                      {
                        "type": "exams",
                        "starts_at": "2015-05-18",
                        "ends_at": "2015-06-27"
                      }
                      {
                        "type": "holiday",
                        "starts_at": "2015-07-01",
                        "ends_at": "2015-08-31"
                      }
                    ]
                  }
                }
/search:
  is: [ paged, secured ]
  get:
    description: >
      Seach courses, people and rooms with the queried string in ID or title.
      This resource is designed especially for an instant search (aka result autosuggestion).
    queryParameters:
      q:
        description: Search query
        type: string
        required: true
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "results": [
                  {
                    "id": "MI-RUB",
                    "title": "Programování v Ruby",
                    "type": "course"
                  },
                  {
                    "id": "rubyelis",
                    "title": "Ing. Elisia Ruby",
                    "type": "person"
                  }
                ],
                "meta": {
                  "offset": 0,
                  "limit": 2
                }
              }

#%RAML 0.8
title: CTU Sirius API
version: v1
baseUri: https://sirius.fit.cvut.cz/api/{version}
securedBy: [access_token]
securitySchemes:
  - access_token:
      description: |
        All Sirius read-only resources are secured by an access token. The token is either
        associated with an username (personal) or is set as global. This authorization
        scheme uses the same query parameter as OAuth 2.0, and will be later
        replaced by OAuth 2.0.
      type: x-access-token
      describedBy:
        queryParameters:
          access_token:
            description: |
              Used to send a valid access token.
            type: string
        responses:
          401:
            description: |
              Missing or invalid token. Authorization token was not specified or is not valid.
traits:
  - paged:
      usage: Retreive further pages in collection
      description: Use `offset` and `limit` to paginate the records.
      queryParameters:
        limit:
          description: The number of entries in collection to return
          type: number
          default: 10
          maximum: 100
        offset:
          description: Offset of the first entry in collection
          type: number
          default: 0
  - dateScoped:
      queryParameters:
        from:
          description: Return events from this date
          type: date
        to:
          description: Return events up to this date
          type: date
        with_original_date:
          description: >
            When the date of event has been changed by a schedule exception, original date is not
            considered for date filtering (by from/to parameters). With this parameter Sirius will
            include events’ original date in a date filter.
          type: boolean
          default: false
  - deletable:
      queryParameters:
        deleted:
          description: Return even events that have been deleted.
          type: boolean
          default: false
  - filterable:
      queryParameters:
        event_type:
          description: Filter by event's type
          type: string
          enum: [ assessment, course_event, exam, laboratory, lecture, tutorial ]
  - includable:
      description: >
        Includes the specified linked resources into the response (similar to compound documents
        in the JSON API format).
      queryParameters:
        include:
          description: A comma-separated list of the link names to include.
          type: string
          example: courses,teachers,schedule_exceptions
  - secured:
      description: Marks resource as secured. You need to be authenticated and authorized to access it.
      queryParameters:
        access_token:
          description: Authentication and authorization is required. You need to set your `access_token` in URL.
          type: string
          example: 07a855e0-6920-11e4-a40a-0002a5d5c51b
          required: true
resourceTypes:
  - events-collection:
      get:
        is: [ dateScoped, deletable, filterable, includable, paged, secured ]
        responses:
          200:
            body:
              application/json:
                example: |
                    {
                      "meta": {
                        "count": 2,
                        "offset": 0,
                        "limit": 20
                      },
                      "events": [
                        {
                          "id": 42,
                          "name": null,
                          "sequence_number": 12,
                          "starts_at": "2014-04-23T09:15:00.000+02:00",
                          "ends_at": "2014-04-23T10:45:00.000+02:00",
                          "deleted" : false,
                          "capacity": 24,
                          "event_type": "tutorial",
                          "parallel": "106",
                          "original_data": {
                            "starts_at": "2014-04-23T09:00:00.000+02:00",
                            "ends_at": "2014-04-23T10:30:00.000+02:00",
                            "room_id": "T9:111"
                          },
                          "links": {
                            "room": "T9:350",
                            "course": "MI-RUB",
                            "teachers": [
                              "skocdopet"
                            ],
                            "students": [
                              "szolatib",
                              "vomackar"
                            ],
                            "applied_exceptions": [ 10, 15 ]
                          }
                        },
                        {
                          "id": 43,
                          "name": null,
                          "sequence_number": 12,
                          "starts_at": "2014-04-24T09:15:00.000+02:00",
                          "ends_at": "2014-04-24T10:45:00.000+02:00",
                          "deleted" : false,
                          "capacity": 196,
                          "event_type": "lecture",
                          "parallel": "1",
                          "original_data": {},
                          "links": {
                            "room": "T9:155",
                            "course": "MI-W20",
                            "teachers": [
                              "kuchajar",
                              "vitvatom"
                            ],
                            "students": [
                              "jirutjak"
                            ]
                          }
                        }
                      ]
                    }
              text/calendar:
                example: |
                  BEGIN:VCALENDAR
                  VERSION:2.0
                  CALSCALE:GREGORIAN
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/123
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/125
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  END:VCALENDAR
          404:
            description: There are no events within the current scope
  - event:
      get:
        is: [ secured ]
        responses:
          200:
            body:
              application/json:
                example: |
                  {
                    "events": {
                      "id": 42,
                      "name": null,
                      "sequence_number": 12,
                      "starts_at": "2014-04-23T07:30:00.000+02:00",
                      "ends_at": "2014-04-23T11:00:00.000+02:00",
                      "deleted" : false,
                      "capacity": 24,
                      "event_type": "tutorial",
                      "parallel": "106",
                      "original_data": {
                        "starts_at": "2014-04-23T09:00:00.000+02:00",
                        "ends_at": "2014-04-23T10:30:00.000+02:00",
                        "room_id": "T9:111"
                      },
                      "links": {
                        "room": "T9:350",
                        "course": "MI-RUB",
                        "teachers": [
                          "skocdopet"
                        ],
                        "students": [
                          "szolatib",
                          "vomackar"
                        ],
                        "applied_exceptions": [ 10, 15 ]
                      }
                    }
                  }
              text/calendar:
                example: |
                  BEGIN:VCALENDAR
                  VERSION:2.0
                  CALSCALE:GREGORIAN
                  BEGIN:VEVENT
                  DTSTAMP:20140702T140133Z
                  UID:https://sirius.fit.cvut.cz/events/123
                  DTSTART:20140312T101500
                  DTEND:20140312T114500
                  CLASS:PUBLIC
                  CREATED:20140410T182546
                  LAST-MODIFIED:20140410T182546
                  LOCATION:T9:130
                  SUMMARY:MI-PSL 2. cvičení
                  END:VEVENT
                  END:VCALENDAR
/events:
  type: events-collection
  get:
    description: "Get all events without any scope"
  /{eventId}:
    type: event
/people/{username}/events:
  type: events-collection
  description: Get a calendar for a person
  uriParameters:
    username:
      description: person's unique username
      required: true
      pattern: "[a-z0-9]{3,8}"
      example: vomackar
/rooms/{kosId}/events:
  type: events-collection
  description: Get a calendar for a room
  uriParameters:
    kosId:
      description: |
        Common room identification used by KOS, for details see [the documentation](https://rozvoj.fit.cvut.cz/Main/znaceni-mistnosti#HKOSEDzna10DenED-102).
      required: true
      pattern: "[A-Z0-9]{2}:([A-Z0-9]+-)?[a-z0-9]+"
      example: "TH:A-1333"
/courses/{courseCode}/events:
  type: events-collection
  description: Get events instances for a given course
  uriParameters:
    courseCode:
      description: |
        Course code, faculty specific.
      required: true
      example: BI-PA1
/schedule_exceptions:
  description: Manage schedule exceptions
  is: [ paged ]
  get:
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "schedule_exceptions": [
                  {
                    "id": 1,
                    "type": "CANCEL",
                    "name": "Den české státnosti",
                    "scope": {
                      "starts_at": "2014-09-28T00:00:00.000+02:00",
                      "ends_at": "2014-09-29T00:00:00.000+02:00",
                      "faculty": null,
                      "semester": null,
                      "courses": null,
                      "timetable_slots": null
                    }
                  },
                  {
                    "id": 11,
                    "type": "CANCEL"
                    "name": "Děkanský den FIT",
                    "note": "Výuka odpadá",
                    "scope": {
                      "starts_at": "2015-04-30T00:00:00Z",
                      "ends_at": "2015-05-01T00:00:00Z",
                      "faculty": 18000,
                      "semester": "B142",
                      "courses": null,
                      "timetable_slots": null
                    }
                  }
                ],
                "meta": {
                  "count": 2,
                  "offset": 0,
                  "limit": 20
                }
              }
  /{id}:
    uriParameters:
      id:
        description: ID of the schedule exception
        required: true
    get:
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "schedule_exceptions": {
                    "id": 7,
                    "type": "ROOM_CHANGE",
                    "name": "MI-MPI - přednáška 24. 9. 2014 přesunuta do T9:105",
                    "scope": {
                      "starts_at": "2014-09-24T00:00:00.000+02:00",
                      "ends_at": "2014-09-25T00:00:00.000+02:00",
                      "faculty": 18000,
                      "semester": "B141",
                      "courses": null,
                      "timetable_slots": [ 392651000 ]
                    },
                    "options": {
                      "room_id": "T9:105"
                    }
                  }
                }
/semesters:
  is: [ paged, secured ]
  get:
    description: Get all semesters per faculties.
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "semesters": [
                  {
                    "id": "18000-B142",
                    "semester": "B142",
                    "faculty": 18000,
                    "starts_at": "2015-02-16",
                    "ends_at": "2015-09-21",
                    "exams_start_at": "2015-05-18",
                    "exams_end_at": "2015-06-27",
                    "teaching_ends_at": "2015-05-16",
                    "first_week_parity": "even",
                    "hour_duration": 45,
                    "hour_starts": [
                      "07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
                      "12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
                      "18:00", "18:45", "19:45"
                    ]
                  }
                ],
                "meta": {
                  "count": 4,
                  "offset": 0,
                  "limit": 1
                }
              }
  /{faculty_semester}:
    is: [ secured ]
    uriParameters:
      faculty_semester:
        description: Faculty code and semester code connected with a dash.
        pattern: "[0-9]{5}-[AB][0-9]{2}[12]"
        example: 18000-B142
        required: true
    get:
      description: Get a semester on a faculty.
      responses:
        200:
          body:
            application/json:
              example: |
                {
                  "semesters": {
                    "id": "18000-B142",
                    "semester": "B142",
                    "faculty": 18000,
                    "starts_at": "2015-02-16",
                    "ends_at": "2015-09-21",
                    "exams_start_at": "2015-05-18",
                    "exams_end_at": "2015-06-27",
                    "teaching_ends_at": "2015-05-16",
                    "first_week_parity": "even",
                    "hour_duration": 45,
                    "hour_starts": [
                      "07:30", "08:15", "09:15", "10:00", "11:00", "11:45",
                      "12:45", "13:30", "14:30", "15:15", "16:15", "17:00",
                      "18:00", "18:45", "19:45"
                    ]
                  }
                }
/search:
  is: [ paged, secured ]
  get:
    description: >
      Seach courses, people and rooms with the queried string in ID or title.
      This resource is designed especially for an instant search (aka result autosuggestion).
    queryParameters:
      q:
        description: Search query
        type: string
        required: true
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "results": [
                  {
                    "id": "MI-RUB",
                    "title": "Programování v Ruby",
                    "type": "course"
                  },
                  {
                    "id": "rubyelis",
                    "title": "Ing. Elisia Ruby",
                    "type": "person"
                  }
                ],
                "meta": {
                  "offset": 0,
                  "limit": 2
                }
              }