api.raml

#%RAML 1.0
title: SPAMD-UL
version: 4.0.0
mediaType: application/json
uses:
  types: ./libraries/types.raml
/api/users:
  description: Collection of users
  post:
    description: Add a new user
    body:
      application/json:
        type: types.User
        example: !include examples/users/post-users-request.json
    responses:
      201:
        description: Id for newly created account of user
        body:
          application/json:
            type: types.AccountIdObject
            example: !include examples/users/post-users-response.json
      400:
        description: Error adding user
  /{accountId}:
    description: User with given account id
    uriParameters:
      accountId:
        type: types.AccountId
    get:
      description: Get the user's information
      responses:
        200:
          description: Requested user
          body:
            application/json:
              type: types.User
              example: !include examples/users/get-users-response.json
        400:
          description: Error getting user
        404:
          description: User not found
    /bills:
      description: Collection of bills for user
      get:
        description: Get the user's bills
        responses:
          200:
            description: Requested user's bills
            body:
              application/json:
                type: types.Bill[]
                example: !include examples/users/get-users-bills-response.json
          400:
            description: Error getting user's bills
          404:
            description: User not found
      /{billId}:
        description: Bill of user with given bill id
        uriParameters:
          billId:
            type: types.BillId
        post:
          description: Pay an amount of the user's bills
          body:
            application/json:
              type: types.BillPayment
              example: !include examples/users/post-users-bills-request.json
          responses:
            200:
              description: Bill after payment
              body:
                application/json:
                  type: types.Bill
                  example: !include examples/users/post-users-bills-response.json
            400:
              description: Error paying user's bills
            404:
              description: User or bill not found
    /cars:
      description: Collection of cars for user
      post:
        description: Add a new car to user
        body:
          application/json:
            type: types.Car
            example: !include examples/users/post-users-cars-request.json
        responses:
          201:
            description: Car successfully added to user
          400:
            description: Error adding car to user
          404:
            description: User not found
          409:
            description: License plate already exists
      get:
        description: Get all cars of user
        responses:
          201:
            description: All cars of user
            body:
              application/json:
                type: types.Car[]
                example: !include examples/users/get-users-cars-request.json
          400:
            description: Error getting cars of user
          404:
            description: User not found
    /accessPasses:
      description: Collection of access passes for user
      post:
        description: Add a access pass to user
        body:
          application/json:
            type: types.AccessPass
            examples:
              "Without car": !include examples/users/post-users-access-passes-request-without-car.json
              "One day a week per semester": !include examples/users/post-users-access-passes-request-one-day-a-week-per-semester.json
              "One semester": !include examples/users/post-users-access-passes-request-one-semester.json
              "Two semesters": !include examples/users/post-users-access-passes-request-two-semesters.json
              "Three semesters": !include examples/users/post-users-access-passes-request-three-semesters.json
        responses:
          201:
            description: Code for newly added access pass
            body:
              application/json:
                type: types.AccessPassCodeObject
                example: !include examples/users/post-users-access-passes-response.json
          400:
            description: Error adding access pass to user
          404:
            description: User or license plate not found
    /bicycleAccessPasses:
      description: Collection of access passes for user
      post:
        description: Add a access pass for bicycle to user
        body:
          application/json:
            type: types.BicycleAccessPass
            examples:
              "With postal": !include examples/users/post-users-bicycle-access-passes-request-with-postal.json
              "With email": !include examples/users/post-users-bicycle-access-passes-request-with-email.json
              "With ssp": !include examples/users/post-users-bicycle-access-passes-request-with-ssp.json
        responses:
          201:
            description: Code for newly added access pass
            body:
              application/json:
                type: types.AccessPassCodeObject
                example: !include examples/users/post-users-access-passes-response.json
          400:
            description: Error adding access pass to user
          404:
            description: User not found
    /parkingStickers:
      description: Collection of parking stickers for user
      post:
        description: Add a parking sticker to user
        body:
          application/json:
            type: types.ParkingSticker
            examples:
              "Send via postal carrier": !include examples/users/post-users-parking-stickers-request-postal.json
              "Sent via email": !include examples/users/post-users-parking-stickers-request-email.json
              "Sent via SSP": !include examples/users/post-users-parking-stickers-request-ssp.json
        responses:
          201:
            description: Code for newly added parking sticker
            body:
              application/json:
                type: types.ParkingStickerCodeObject
                example: !include examples/users/post-users-parking-stickers-response.json
          400:
            description: Error adding parking sticker to user
          404:
            description: User not found
/api/parkingAreas:
  description: Collection of parking areas
  get:
    description: Get all parking areas
    responses:
      200:
        description: All parking areas
        body:
          application/json:
            type: types.ParkingArea[]
            example: !include examples/parkingAreas/get-parking-areas-response.json
      400:
        description: Error getting all parking areas
/api/gates:
  description: Gate entry for campus access
  /entry:
    /validateAccessPassWithCode:
      /{code}:
        description: Validates an access pass for entering with a given code
        uriParameters:
          code:
            type: types.AccessPassCode
        post:
          description: Validate the access pass with given code
          body:
            application/json:
              type: types.AccessDateTimeObject
              example: !include examples/gates/post-gates-entry-validate-access-pass-request.json
          responses:
            202:
              description: Access status of access pass is granted
              body:
                application/json:
                  type: types.AccessStatusObject
                  example: !include examples/gates/post-gates-entry-validate-access-pass-response-granted.json
            400:
              description: Error validating access pass
            403:
              description: Access status of access pass is refused
              body:
                application/json:
                  type: types.AccessStatusObject
                  example: !include examples/gates/post-gates-entry-validate-access-pass-response-refused.json
            404:
              description: Access pass not found
    /validateAccessPassWithLicensePlate:
      /{licensePlate}:
        description: Validates an access pass for given license plate
        uriParameters:
          licensePlate:
            type: types.LicensePlate
        post:
          description: Validate the access pass with given license plate
          body:
            application/json:
              type: types.AccessDateTimeObject
              example: !include examples/gates/post-gates-entry-validate-access-pass-request.json
          responses:
            202:
              description: Access status of access pass is granted
              body:
                application/json:
                  type: types.AccessStatusObject
                  example: !include examples/gates/post-gates-entry-validate-access-pass-response-granted.json
            400:
              description: Error validating access pass
            403:
              description: Access status of access pass is refused
              body:
                application/json:
                  type: types.AccessStatusObject
                  example: !include examples/gates/post-gates-entry-validate-access-pass-response-refused.json
            404:
              description: Access pass or license plate not found
  /exit:
    /validateAccessPassWithCode:
      /{code}:
        description: Validates an access pass for entering with a given code
        uriParameters:
          code:
            type: types.AccessPassCode
        post:
          description: Validate the access pass with given code
          responses:
            200:
              description: Gate exit was successful
            404 :
              description: Access pass not found
    /validateAccessPassWithLicensePlate:
      /{licensePlate}:
        description: Validates an access pass for given license plate
        uriParameters:
          licensePlate:
            type: types.LicensePlate
        post:
          description: Validate the access pass with given license plate
          responses:
            200:
              description: Gate exit was successful
            404 :
              description: Access pass or license plate not found
/api/offenses:
  description: Collection of offenses
  /types:
    description: Collection of all possible offense types
    get:
      description: Get all possible offense types
      responses:
        200:
          description: All offense types
          body:
            application/json:
              type: types.OffenseType[]
              example: !include examples/offenses/get-offense-types-response.json
        400:
          description: Error getting offense types
  /validate:
    description: Validations of offenses
    post:
      description: Check offense for the parking sticker
      body:
        application/json:
          type: types.OffenseValidation
          example: !include examples/offenses/get-offenses-validate-request.json
      responses:
        200:
          description: |
            List of offense types of parking sticker code

            An offense with a valid parking sticker code will generate a bill to its associated
            user, with the exception of an offense for an invalid (or absent) parking sticker code.
            In that case, the offense type will be correctly responded but no bill will be
            generated, since it would be impossible to find a user.
          body:
            application/json:
              type: types.OffenseType[]
              examples:
                "With offense types": !include examples/offenses/get-offenses-validate-response-with-offense-types.json
                "Without offense type": !include examples/offenses/get-offenses-validate-response-without-offense-type.json
        400:
          description: Error getting offense type for parking sticker
        404:
          description: Parking sticker not found
/api/initiatives:
  description: Collection of funding initiatives
  post:
    description: Add a new funding initiative
    body:
      application/json:
        type: types.Initiative
        example: !include examples/initiatives/post-initiatives-request.json
    responses:
      201:
        description: Funding initiative successfully added
        body:
          application/json:
            type: types.InitiativeCodeObject
            example: !include examples/initiatives/post-initiatives-response.json
      400:
        description: Error adding funding initiative
  get:
    description: Get all funding initiatives
    responses:
      200:
        description: All funding initiatives
        body:
          application/json:
            type: types.Initiative[]
            example: !include examples/initiatives/get-initiatives-response.json
      400:
        description: Error getting funding initiative
  /{initiativeCode}:
    description: An initiative with given code
    uriParameters:
      initiativeCode:
        type: types.InitiativeCode
    post:
      description: Add amount to initiative
      body:
        application/json:
          type: types.InitiativeAmountToAdd
          example: !include examples/initiatives/post-initiatives-added-amount-request.json
      responses:
        200:
          description: Amount successfully added to initiative
        400:
          description: Error adding amount to initiative
        404:
          description: Initiative not not found
    get:
      description: Get information about an initiative
      responses:
        200:
          description: Information about an initiative
          body:
            application/json:
              type: types.Initiative
              example: !include examples/initiatives/get-initiative-response.json
        400:
          description: Error getting initiative
        404:
          description: Initiative not found
  /availableAmount:
    description: Available amount for funding initiatives
    get:
      description: Get available amount for funding initiatives
      responses:
        200:
          description: Available amount for funding initiatives
          body:
            application/json:
              type: types.AvailableAmountForInitiatives
              example: !include examples/initiatives/get-initiatives-available-amount-response.json
        400:
          description: Error getting funding initiative
/api/carbonCredits:
  description: Information about carbon credits purchased with generated profits
  post:
    description: Enable or disabled monthly payment of carbon credits
    body:
      application/json:
        type: types.CarbonCreditMonthlyPaymentStatusObject
        example: !include examples/carbonCredits/post-carbon-credits-request.json
    responses:
      200:
        description: Carbon credit monthly payment status successfully changed
      400:
        description: Error changing carbon credit monthly payment status
  get:
    description: Get amount of purchased carbon credits
    responses:
      200:
        description: Amount of purchased carbon credits
        body:
          application/json:
            type: types.CarbonCreditAmount
            example: !include examples/carbonCredits/get-carbon-credits-request.json
      400:
        description: Error getting amount of purchased carbon credits
/api/reports:
  description: Various reports available for the application
  /profits:
    description: Profits generated by parking stickers, access passes and offenses
    /parkingStickers:
      description: Profits generated by parking stickers
      get:
        description: Get profits generated by parking stickers for given year
        queryParameters:
          year:
            description : Year for profits query
            required: false
            default: Current year
            type: types.Year
        responses:
          200:
            description: Report of profits generated by parking stickers for given year
            body:
              application/json:
                type: types.ReportPeriod[]
                example: !include examples/reports/get-reports-profits-parking-stickers-response.json
          400:
            description: Error getting profits for parking stickers
    /accessPasses:
      description: Profits generated by access passes
      get:
        description: Get profits generated by access passes for given year
        queryParameters:
          year:
            description : Year for profits query
            required: false
            default: Current year
            type: types.Year
          byConsumptionType:
            description : Separate access passes profits by consumption type (true or false)
            required: false
            default: false
            type: string
        responses:
          200:
            description: Report of profits generated by access passes for given year
            body:
              application/json:
                type: types.ReportPeriod[]
                examples:
                  notByConsumptionType: !include examples/reports/get-reports-profits-access-passes-response.json
                  byConsumptionType: !include examples/reports/get-reports-profits-access-passes-by-consumption-type-response.json
          400:
            description: Error getting profits for access passes
    /offenses:
      description: Profits generated by offenses
      get:
        description: Get profits generated by offenses for given year
        queryParameters:
          year:
            description : Year for profits query
            required: false
            default: Current year
            type: types.Year
        responses:
          200:
            description: Profits generated by offenses for given year
            body:
              application/json:
                type: types.ReportPeriod[]
                example: !include examples/reports/get-reports-profits-offenses-response.json
          400:
            description: Error getting profits for offenses
  /parkingAreas:
    description: Gate entries by parking areas
    get:
      description: Get gate entries by parking areas for given parameters
      queryParameters:
        reportType:
          type: types.ReportType
          default: monthly
        month:
          description: Month for dayOfMonth or summary report type
          type: String
          default: Current month
      responses:
        200:
          description: Gate entries by parking areas for given parameters
          body:
            application/json:
              type: types.ReportPeriod[]
              examples:
                "Monthly report type": !include examples/reports/get-reports-parking-areas-monthly-response.json
                "Day of month report type": !include examples/reports/get-reports-parking-areas-day-of-month-response.json
                "Summary report type": !include examples/reports/get-reports-parking-areas-summary-response.json
        400:
          description: Error getting gate entires by parking areas