Updates related to sub-directory renames

References to '/Libraries' changed to 'libraries'

#%RAML 1.0
title: Digitale Delta - Operational (DD-OPER) API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication

baseUri: http://api.rws.nl/dl/

mediaType: [ application/json ]

description: Digital Delta - Operational API
documentation:
  - title: Introduction
    content: The Digital Delta is a distributed network in which various data sources exchange information using a standard web service interface.
      The architecture and additional description of the Digital Delta can be found on ... (TODO refer to digitaldelta.org once it is updated - end of August).
      The present document contains the specification of the Digital Delta web service API. It uses the RAML standard as the definition language.

  - title: The API specification
    content: This API describes 'DD-OPER', which is a series of additional endpoints to the 'DD API'. The structure of the /timeseries response
      of DD-OPER API is in line with the /timeseries response defined by DD-API, but will provide a different (sub)set of the information.

  - title: Modification History
    content: |
      Date          Author      Description
      2018-04-01    RWS         New version created based on DD API 1.0 and MKK-DL API 1.0
      2018-04-20    RWS         End-points and request parameters finalised. Naming conventions alligned with DD API 1.9 proposal.
      2018-07-07    RWS         Changed to dd-oper version 2.0 and now as Extension of DD-API 2.0 raml.
      2018-07-18    RWS         Change to error/problem response due to DD API 2.0 change.
      2018-09-11    RWS         References to '/Libraries' changed to 'libraries'

  - title: Todo
    content: |
      - Update documentation/description texts. It will also be placed in external files such that updates will not impact raml itself.
      - Add error response codes to all responses.  most are done, just need sanity check.

# HTTP protocol is included as (optional) protocol for internal use. HTTPS support is mandatory for external communication.
protocols: [HTTP, HTTPS]

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

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

traits:
  #
  # Responses Error Codes
  #
  has400-InvalidRequestError:
    responses:
      400:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json
  has404-NotFoundError:
    responses:
      404:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json
  has500-ServerError:
    responses:
      500:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json

# The resources:
/dd-oper/2.0:
  description:
    The 'dd-oper' section in the url is mandatory as it is used to distinguish similar endpoints in the DD API   (/dd/2.0).

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

  /aspectSets:
    description:
      Retrieves full list of available aspect sets.
    get:
      queryParameters:
      responses:
        200:
          description: |
            Succesfully retrieved resource
          body:
            application/json:
              type: DDOPER-RESP.AspectSetListResponse
              example: !include examples/dd-oper/dd-oper-aspectsetlist-response.json

# ########################################################
  /locations:
    description: The Locations endpoint returns the complete list of locations within the NL.RWS.WM namespace that the Provider offers.
           There are no filterings options.
    get:
      queryParameters:
      responses:
        200:
          body:
            application/json:
              type: DDOPER-RESP.LocationListResponse
              example: !include examples/dd-oper/dd-oper-locationslist-response.json

    /{locationName}:
      description:  Request a specific location by its matching name (caseless match).
      uriParameters:
        locationName:
          type: DD-T.LocationName
      get:
        description: |
          The resource request for details of a single location is not yet supported
        responses:
          200:
            body:
              application/json:
                type: object
                example: !include examples/dd-oper/dd-oper-location-response.json
      is: [has400-InvalidRequestError, has404-NotFoundError]

######################################################
      /quantities:
        description: |
          The quantities endpoint returns the list of parameters available at the selected location.
        get:
          queryParameters:
          responses:
            200:
              body:
                application/json:
                  type: DDOPER-RESP.QuantityListResponse
                  example: !include examples/dd-oper/dd-oper-quantitylist-response.json

        /{quantityName}:
          uriParameters:
            quantityName:
              type: DD-T.QuantityName
          get:
            description: Request a specific quantity by its name. This request is not yet supported.
            responses:
              200:
                body:
                  application/json:
                    type: DDOPER-RESP.QuantityResponse
                    example: !include examples/dd-oper/dd-oper-quantity-response.json
          is: [has400-InvalidRequestError, has404-NotFoundError]

############################################################
          /timeseries:
            get:
              description: |
                Retrieve resource
              queryParameters:
                startTime:
                  type: DD-T.StartTime
                  required: true
                endTime:
                  type: DD-T.EndTime
                  required: false
                intervalLength:
                  type: DD-T.IntervalLength
                  required: false
                  default: 10min
                aspectSet:
                  type: DD-T.AspectSetName
                  required: false
                  default: standard
                process:
                  type: DD-T.ProcessName
                  required: true
                  default: measurement
              responses:
                200:
                  description: |
                    Succesfully retrieved timeseries
                  body:
                    application/json:
                      type: DDOPER-RESP.TimeseriesListResponse
                      example: !include examples/dd-oper/dd-oper-timeseries-full-response.json
            is: [has400-InvalidRequestError, has500-ServerError]

#%RAML 1.0
title: Digitale Delta - Operational (DD-OPER) API
version: 2.0
securitySchemes:
  basic:
    type: Basic Authentication

baseUri: http://api.rws.nl/dl/

mediaType: [ application/json ]

description: Digital Delta - Operational API
documentation:
  - title: Introduction
    content: The Digital Delta is a distributed network in which various data sources exchange information using a standard web service interface.
      The architecture and additional description of the Digital Delta can be found on ... (TODO refer to digitaldelta.org once it is updated - end of August).
      The present document contains the specification of the Digital Delta web service API. It uses the RAML standard as the definition language.

  - title: The API specification
    content: This API describes 'DD-OPER', which is a series of additional endpoints to the 'DD API'. The structure of the /timeseries response
      of DD-OPER API is in line with the /timeseries response defined by DD-API, but will provide a different (sub)set of the information.

  - title: Modification History
    content: |
      Date          Author      Description
      2018-04-01    RWS         New version created based on DD API 1.0 and MKK-DL API 1.0
      2018-04-20    RWS         End-points and request parameters finalised. Naming conventions alligned with DD API 1.9 proposal.
      2018-07-07    RWS         Changed to dd-oper version 2.0 and now as Extension of DD-API 2.0 raml.
      2018-07-18    RWS         Change to error/problem response due to DD API 2.0 change.

  - title: Todo
    content: |
      - Update documentation/description texts. It will also be placed in external files such that updates will not impact raml itself.
      - Add error response codes to all responses.  most are done, just need sanity check.

# HTTP protocol is included as (optional) protocol for internal use. HTTPS support is mandatory for external communication.
protocols: [HTTP, HTTPS]

uses:
    DD-T: Libraries/dd-base-types.raml
    DDOPER-T: Libraries/ddoper-base-types.raml
    GENERIC-RESP: /Libraries/generic-response-types.raml
    DDOPER-RESP: /Libraries/ddoper-response-types.raml

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

traits:
  #
  # Responses Error Codes
  #
  has400-InvalidRequestError:
    responses:
      400:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json
  has404-NotFoundError:
    responses:
      404:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json
  has500-ServerError:
    responses:
      500:
        body:
          application/json:
            type: GENERIC-RESP.ErrorResponse
            example: !include examples/dd-oper/dd-oper-error-response.json

# The resources:
/dd-oper/2.0:
  description:
    The 'dd-oper' section in the url is mandatory as it is used to distinguish similar endpoints in the DD API   (/dd/2.0).

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

  /aspectSets:
    description:
      Retrieves full list of available aspect sets.
    get:
      queryParameters:
      responses:
        200:
          description: |
            Succesfully retrieved resource
          body:
            application/json:
              type: DDOPER-RESP.AspectSetListResponse
              example: !include examples/dd-oper/dd-oper-aspectsetlist-response.json

# ########################################################
  /locations:
    description: The Locations endpoint returns the complete list of locations within the NL.RWS.WM namespace that the Provider offers.
           There are no filterings options.
    get:
      queryParameters:
      responses:
        200:
          body:
            application/json:
              type: DDOPER-RESP.LocationListResponse
              example: !include examples/dd-oper/dd-oper-locationslist-response.json

    /{locationName}:
      description:  Request a specific location by its matching name (caseless match).
      uriParameters:
        locationName:
          type: DD-T.LocationName
      get:
        description: |
          The resource request for details of a single location is not yet supported
        responses:
          200:
            body:
              application/json:
                type: object
                example: !include examples/dd-oper/dd-oper-location-response.json
      is: [has400-InvalidRequestError, has404-NotFoundError]

######################################################
      /quantities:
        description: |
          The quantities endpoint returns the list of parameters available at the selected location.
        get:
          queryParameters:
          responses:
            200:
              body:
                application/json:
                  type: DDOPER-RESP.QuantityListResponse
                  example: !include examples/dd-oper/dd-oper-quantitylist-response.json

        /{quantityName}:
          uriParameters:
            quantityName:
              type: DD-T.QuantityName
          get:
            description: Request a specific quantity by its name. This request is not yet supported.
            responses:
              200:
                body:
                  application/json:
                    type: DDOPER-RESP.QuantityResponse
                    example: !include examples/dd-oper/dd-oper-quantity-response.json
          is: [has400-InvalidRequestError, has404-NotFoundError]

############################################################
          /timeseries:
            get:
              description: |
                Retrieve resource
              queryParameters:
                startTime:
                  type: DD-T.StartTime
                  required: true
                endTime:
                  type: DD-T.EndTime
                  required: false
                intervalLength:
                  type: DD-T.IntervalLength
                  required: false
                  default: 10min
                aspectSet:
                  type: DD-T.AspectSetName
                  required: false
                  default: standard
                process:
                  type: DD-T.ProcessName
                  required: true
                  default: measurement
              responses:
                200:
                  description: |
                    Succesfully retrieved timeseries
                  body:
                    application/json:
                      type: DDOPER-RESP.TimeseriesListResponse
                      example: !include examples/dd-oper/dd-oper-timeseries-full-response.json
            is: [has400-InvalidRequestError, has500-ServerError]


Fix semantic error in RAML

Fix semantic error in 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
  - 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
                }
              }

#%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
  - 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 ]
  queryParameters:
    q:
      description: Search query
      type: string
      required: true
  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).
    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
                }
              }


Incorporated review comments

Incorporated review comments

#%RAML 0.8
---
title: Invoice API
baseUri: https://www.mybring.com

documentation:
- title: Introduction
  content: |
      The Invoice API is used to download the invoice pdfs same as in Mybring.

- title: Authentication
  content: |
    The Invoice 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 |
    | `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.

/invoicearchive/pdf/{invoiceType}/{customerNumberUnique}/{invoiceNumber}.pdf:
  displayName: Invoice PDF download endpoint
  securedBy: [mybring_headers, null]
  description: |
      This link is used to download the invoice pdf for the customer by providing the type of invoice (NORMAL or SPECIFIED) based on customer type along with API Customer Id and invoice number in URI params

  uriParameters:
    invoiceType:
      description: Type can be NORMAL and SPECIFIED for particular customers
    customerNumberUnique:
      description: Unique API Customer Number for each customer.
    invoiceNumber:
      description: Invoice number of the particular invoice to be downloaded.

  get:
    description: Download pdf for invoice

/reports/api/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List of all Invoice
  description: |
    Use the existing [Reports Api List invoice numbers](/api/reports/#list-invoice-numbers) for this feature.
  uriParameters:
      customerOrGroupId:
        description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.  For e.g. GROUP_12345
        type: string
        required: true
      mediaTypeExtension:
        enum: [ .json, .xml ]
        description: Use .json to specify application/json or .xml to specify application/xml

  get:
    description: List invoice numbers

#%RAML 0.8
---
title: Invoice API
baseUri: https://www.mybring.com

documentation:
- title: Introduction
  content: |
      The Invoice API is used to download the invoice pdfs same as in mybring.

- title: Authentication
  content: |
    The Invoice 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 |
    | `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.

/invoicearchive/pdf/{invoiceType}/{customerNumberUnique}/{invoiceNumber}.pdf:
  displayName: Invoice PDF download endpoint
  securedBy: [mybring_headers, null]
  description: |
      This link is used to download the invoice pdf for the customer by providing the type of invoice (NORMAL or SPECIFIED) based on customer type along with API Customer Id and invoice number in URI params

  uriParameters:
    invoiceType:
      description: Type can be NORMAL and SPECIFIED for particular customers
    customerNumberUnique:
      description: Unique API Customer Number for each customer.
    invoiceNumber:
      description: Invoice number of the particular invoice to be downloaded.

  get:
    description: Download pdf for invoice

/reports/api/invoices/{customerOrGroupId}{mediaTypeExtension}:
  displayName: List of all Invoice using existing Reports API
  description: |
    Use the existing [Reports Api List invoice numbers](/api/reports/#list-invoice-numbers) for this feature.
  uriParameters:
      customerOrGroupId:
        description: Id for customer or customer group. Customer group id should have the prefix `GROUP_`.
        type: string
        required: true
      mediaTypeExtension:
        enum: [ .json, .xml ]
        description: Use .json to specify application/json or .xml to specify application/xml

  get:
    description: List invoice numbers


test of rw permission.

test of rw permission.

#%RAML 1.0
title: Pet shop
version: 1
baseUri: /shop

types:
  Pet:
    properties:
      name: string
      kind: string
      price: number
    example:
      name: "Snoopy"
      kind: "Mammal"
      price: 550

/pets:
  get:
    responses:
      200:
        body:
          application/json:
            type: Pet[]
  post:
    body:
      application/json:
        type: Pet
  /{id}:
    put:
      body:
        application/json:
          type: Pet
    delete:
      responses:
        204:

#%RAML 1.0
title: Pet shop
version: 1
baseUri: /shop

types:
  Pet:
    properties:
      name: string
      kind: string
      price: number
    example:
      name: "Snoopy"
      kind: "Mammal"
      price: 100

/pets:
  get:
    responses:
      200:
        body:
          application/json:
            type: Pet[]
  post:
    body:
      application/json:
        type: Pet
  /{id}:
    put:
      body:
        application/json:
          type: Pet
    delete:
      responses:
        204:


Add field

Add field

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing cutomer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

- title: Authentication
  content: |
    The Order Management 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 |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/order/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_purchaseorder.xml

/order:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order. Order, OrderResponse, SalesOrder, NotifyTransport, PurchaseOrder, ArticleBalance, DespatchAdvice, ReceivingAdvice, PackageList.
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      TransportService BasicServiceCode
          description: Transport product for shipment to customer.
          type: String
          required: true
          example: SERVICEPAKKE
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: string
          required: false
          example: 123-4000
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get status for order
  description: |
      Check status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json

#%RAML 0.8
---
title: Order Management API
baseUri: https://api.bring.com/po/api/v1

documentation:
- title: Introduction
  content: |
    There are different customer types in Order Management and depending on what kind of customer you are setts the usage pattern for Order Management API.

    This is a step-by-step guide on how to use the API.

    A typical usage pattern for an Warehousing cutomer type is to create an order in Order Management that will go to the correct warehouse for picking, packing and sending. Then follow up with creating a packing list from the warehouse with transport information. All steps can be followed in Order Management.

    An other usage pattern is for an purchase order customer that create purchase orders and lets all of his suppliers get the order from Order Management. The suppliers will check whether a customer is a Order Management customer. Follow up with creating a packing list with transport information. All events and status changes will go back to purchase order owner.

    Order Management has several interfaces (SOAP and XML/JSON). Choose the option that fits your needs best (see table below). The SOAP interface is the core interface with complete functionality.

    Please note that this API currently doesn't support json on all of its methods yet. Look in the example section to see which are supported.

    ## SOAP

    ### Versioning

    Order Management makes an effort to always be backwards compatible regarding data format for requests and responses of the Web Service. To achieve this, a SchemaVersion element is used in the request, indicating which version the client is on and what data-format the client expects in the result.

    We make an effort not to return new elements in the response when an old schema version is specified. When changes in the schema are made, the SchemaVersion is incremented by one. The new schema is used at the same endpoint URL as before and uses the same namespace for its XML elements. A TraceMessage element (info message) in the response is added to inform the client that its schema should be updated. Old schema versions might in the future be unsupported.

    Regarding the XML API (not Web Services), an XML Schema is not used at all. Therefore, clients of the XML API are expected to handle new elements that appear. Nevertheless, the response will be backwards compatible in the sense that elements are not renamed or deleted.

    ### WSDL

    [https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl](https://api.bring.com/po/api/ws/purchaseorder-v1.wsdl)

    ## Error handling

    When using the Order Management, errors or service unavailability can occur, although we do our utmost to prevent any downtime. Thus it is important to use timeouts and other error handling techniques when making requests to the service.

    How you handle errors depends on the nature of your application, but one strategy for handling such situations is by providing a failover if the shipping guide responds with an error or does not respond at all (timeout).

    See [the list of error codes](#list-error-codes) for hints on how to implement error handling.

- title: Authentication
  content: |
    The Order Management 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 |
    | `X-Bring-Client-URL` | `https://example.com/ ` | A URL that sort of identifies where you're using the APIs. |

    Those headers must be set for all endpoints documented below.

/purchaseorderCustomer/{customerId}:
  displayName: Check if customer is valid for order management
  description: |
      Check if a given customer number is an valid Order Management customer.
  get:
    description:
     Check if customer is valid for order management
    responses:
      200:
        displayName: Success
        description: |
          Returns `true` if given customer is a valid for order management.
        body:
          application/xml:
            example: !include examples/verify_customer.xml
          application/json:
            example: !include examples/verify_customer.json

/order/{customerId}/{orderId}:
  displayName: List order information
  description: |
      Get all information on a given order.
  get:
    description: List order information
    responses:
      200:
        displayName: Success
        description: |
          Complete order information including order items.
        body:
          application/xml:
            example: !include examples/retrieve_purchaseorder.xml

/order:
  displayName: Send an order
  description: |
      Send an order to Order Management. There are different types of order supported in Order Management.

       - Order / SalesOrder (as an pickorder for Warehousing)
            - Order Management act as an order repository.
            - When Warehousing functionality Order Management sends it to Warhousing system for picking and delivery.
       - PurchaseOrder
            - Order Management can give your suppliers access to purchase orders so they can get info, confirm, accept and deliver on them.
            - When Warehousing functionality Order Management sends it to Warhousing system for receiving notice.

  post:
    description: Send an order
    queryParameters:
      CreateOrderRequest messageFunction:
          description: Type of order. Order, OrderResponse, SalesOrder, NotifyTransport, PurchaseOrder, ArticleBalance, DespatchAdvice, ReceivingAdvice, PackageList.
          type: string
          required: true
          example: Order
      MessageSender partyId:
          description: Customer Number which Bring has provided. It cannot be demo customer number.
          type: string
          required: true
          example: 10000000000
      MessageRecipient partyId:
          description: Receiving Bring system. Constant value.
          type: string
          required: true
          example: NO98466118506
      MessageDate:
          description: The date on which message is sent.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      OrderSet updateIndicator:
          description: Type of order data. Original, Update or Deletion
          type: string
          required: true
          example: Original
      Order orderId:
          description: Ordernumber.
          type: dateTime
          required: true
          example: 101010
      Reference:
          description: Set of references.
          type: sequence
          required: false
      Reference referenceType:
          description: Type of reference coded. https://www.stylusstudio.com/edifact/D04A/1153.htm
          type: String
          required: true
          example: CMR
      Reference ReferenceNo:
          description: Reference.
          type: String
          required: true
          example: 10003455TT
      DateAndTimes subClass DocumentDate:
          description: The date on which order is booked.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22
      Party/subClass OrderingParty:
          description: Details of sender. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass DeliveryParty:
          description: Details of recipient. Must have Name, Street, City, CountryCode.
          required: true
      Party/subClass Supplier:
          description: Details of supplier. Must have Name, Street, City, CountryCode if used.
          required: false
      OrderLineSet:
          description: Set of order items.
          type: sequence
          required: true
      OrderItem articleLineId:
          description: Line id for this order line.
          type: integer
          required: true
          example: 10
      ArticleId:
          description: Article number or id.
          type: string
          required: false
          example: 123-4000
      ArticleQuantity unitCode:
          description: Unit code for quantity ordered.
          type: string
          required: true
          example: STK
      ArticleQuantity:
          description: Quantity ordered.
          type: float
          required: true
          example: 2.0
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      Description:
          description: Article description / name.
          type: string
          required: true
          example: Spear parts
      DateAndTimes subClass DeliveryDateRequested:
          description: The date on which order is requested delivered.
          type: dateTime
          required: true
          example: 22.01.2017 11:36:22

    body:
        application/xml:
          example: !include examples/create_order.xml
        application/json:
          example: !include examples/create_order.json
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a order.

/items/{customerId}/{orderId}:
  displayName: List order items
  description: |
      List all item lines on an order.
  get:
    description: List order items
    responses:
      200:
        displayName: Success
        description: |
          List of order items.
        body:
          application/xml:
            example: !include examples/retrieve_orderitems.xml
          application/json:
            example: !include examples/retrieve_orderitems.json

/packaginglist/{customerId}/{orderId}:
  displayName: List packaging list for order
  description: |
      List all packaging list information for this order. One order can have multiple packaging lists.
  get:
    description: List packaging list for order
    responses:
      200:
        displayName: Success
        description: |
          List of packaging list for given order, if any.
        body:
          application/xml:
            example: !include examples/retrieve_packinglist.xml
          application/json:
            example: !include examples/retrieve_packinglist.json

/packaginglist:
  displayName: Add packaging list
  description: |
      When an order have been picked and sent, add packing list on order with transport information.
  post:
    description: Add packaging list
    body:
      application/xml:
        example: !include examples/create_packaging_list.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully added packaging list.

/senderStatus/{customerId}/{orderId}:
  displayName: Get status for order
  description: |
      Check status for an order. Open when not fully delivered or locked when fully delivered.
  get:
    description: Get status for order
    responses:
      200:
        displayName: Success
        description: Open or Locked.
        body:
          application/xml:
            example: !include examples/check_status.xml
          application/json:
            example: !include examples/check_status.json

/event:
  displayName: Create TMSEvents
  description: |
      Create tracking events on shipments associated with orders in Order Management.
  post:
    description: Create TMSEvents
    body:
      application/xml:
        example: !include examples/create_events.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created a new resource

/articlebalance:
  displayName: Create or update article balance list
  post:
    description: Create or update article balance list
    body:
      application/xml:
        example: !include examples/create_articlebalance.xml
    responses:
      200:
        displayName: Success
        description: |
          Successfully created balance list

/articlebalance/{customerId}:
  displayName: Get stock balance and info for all articles
  get:
    description: Get stock balance and info for all articles
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_all.xml
          application/json:
            example: !include examples/retrieve_articlebalance_all.json

/articlebalance/{customerId}/{articleNo}:
  displayName: Get stock balance and info for one article
  get:
    description: Get stock balance and info for one article
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_one.xml
          application/json:
            example: !include examples/retrieve_articlebalance_one.json

/articlebalance/info/{customerId}/{articleSearchString}:
  displayName: Get stock balance and info for all articles matching search string
  get:
    description: Get stock balance and info for all articles matching search string
    responses:
      200:
        displayName: Success
        description: |
        body:
          application/xml:
            example: !include examples/retrieve_articlebalance_search.xml
          application/json:
            example: !include examples/retrieve_articlebalance_search.json

/errorCodes:
  displayName: List error codes
  get:
    description: List error codes
    responses:
      200:
        displayName: Success
        description: |
          Dynamic list of error codes used in the solution.
        body:
          application/xml:
            example: !include examples/error_codes.xml
          application/json:
            example: !include examples/error_codes.json