api-spec.yaml

swagger: '2.0'
info:
  title: Carleton Sesquicentennial API
  description: Content Delivery for the Carleton Sesquicentennial Mobile Apps
  version: 0.0.1
host: api.carleton.edu
schemes:
  - https
basePath: /1.0
produces:
  - application/json
paths:
  /geofences:
    post:
      summary: Geofences close to your location
      description: >
        The Landmarks endpoint delivers Geofence objects representing points of
        interest that are close by and their location
      parameters:
        - name: request
          in: body
          schema:
            type: object
            properties:
              geofence:
                $ref: '#/definitions/Geofence'
              timespan:
                $ref: '#/definitions/Timespan'
                description: Year from which to collect historical information associated with the landmark (note that it will return closest year to the one given that is more recent than the year given)
          description: A current location, a radius in which to search (a geofence) and a timespan with which to limit the search
          required: true
      tags:
        - Landmarks
      responses:
        '200':
          description: An array of geofences
          schema:
            type: array
            items:
              $ref: '#/definitions/Landmark'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /landmarkinfo:
    post:
      summary: Returns information about landmarks that are triggered within the client.
      description: >
        The landmark information endpoint delivers objects that have information on various points of interest, and are associated by name to geofences.
      parameters:
        - name: request
          in: body
          schema:
            type: object
            properties:
              geofences: 
                type: array
                description: An array of the geofences that have been triggered
                items: 
                  type: string
              timespan:
                $ref: '#/definitions/Timespan'
                description: Year from which to collect historical information associated with the landmark (note that it will return closest year to the one given that is more recent than the year given)
          description: A set of geofences that are triggered and the relevant timespan
          required: true
      tags:
        - Landmarks
      responses:
        '200':
          description: An array of landmarks with information
          schema:
            type: array
            items:
              $ref: '#/definitions/LandmarkInfo'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /events:
    post:
      summary: Returns a list of upcoming event objects
      description: >
        The upcoming endpoint delivers event objects representing events based on a timestamp.
      parameters:
        - name: request
          in: body
          schema:
            type: object
            properties:
              startTime:
                type: string
                description: The earliest date from which to get data
              limit:
                type: number
                format: integer
                description: Number of objects to return
          description: latest event to return
          required: true
      tags:
        - Events
      responses:
        '200':
          description: An array of events
          schema:
            type: array
            items:
              $ref: '#/definitions/Event'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /feed:
    post:
      summary: Recent tagged images in the Sesquicentennial social feed
      description: "The images endpoint allows users to get images from the Sesquicentennial social feed from the app. \n"
      parameters:
        - name: request
          in: body
          schema:
            type: object
            properties:
              limit:
                type: number
                format: integer
                description: 'Limit on the number of images to return, again with the most recent first.'
              timestamp:
                type: string
                description: 'Latest date to return images from, most recent first.'
          description: object query for getting images from the feed
          required: true
      tags:
        - Social
      responses:
        '200':
          description: An array of image URLs associated with the time period specified.
          schema:
            type: array
            items:
              type: string
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /quest:
    post:
      summary: Returns quests with a bunch of small challenges to complete. 
      description: >
        The quest endpoint sends quests with a picture, description, title, and multiple wayPoint objects, which in turn have a geofence, a clue, and hint. 
      parameters:
        - name: request
          in: body
          schema:
            type: object
            properties:
              theme:
                type: string
                description: A theme for the desired quests
              limit:
                type: number
                format: integer
                description: A limit on the number of quests to be sent
      tags:
        - Quest
      responses:
        '200':
          description: An array of quests
          schema:
            type: array
            items:
              $ref: '#/definitions/Waypoint'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  Waypoint:
    type: object
    properties:
      clue:
        type: string
        description: clue on how to get to the next level
      hint: 
        type: string
        description: a further clue to help you find the Waypoint
      geofence:
        $ref: '#/definitions/Geofence'
        description: coordinates for the Waypoint
  Event:
    type: object
    properties:
      time:
        type: string
        description: time of event
      venue:
        type: string
        description: human readable location of event
      geofence:
        $ref: '#/definitions/Geofence'
        description: coordinates for venue
  Location:
    type: object
    properties:
      latitude:
        type: number
        format: double
        description: Latitude component of location.
      longitude:
        type: number
        format: double
        description: Longitude component of location.
  Geofence:
    type: object
    properties:
      location:
        $ref: '#/definitions/Location'
        description: location of the center of the geofence
      radius:
        type: number
        format: double
        description: radius in meters of the geofence.
  Timespan:
    type: object
    properties:
      startTime:
        type: string
        format: date
        description: start of time range
      endTime:
        type: string
        format: date
        description: end of time range
  LandmarkInfo:
    type: object
    properties:
      id: 
        type: number
        format: integer
        description: A unique identification value for this landmark
      name:
        type: string
        description: Name of the landmark associated with the information
      type:
        type: string
        description: The type of landmark
      summary:
        type: string
        description: A short snippet about the landmark
      time: 
        type: number
        format: integer
        description: The relevant year
  Landmark:
    type: object
    properties:
      id: 
        type: number
        format: integer
        description: A unique identification value for this geofence
      name:
        type: string
        description: Name of the landmark associated with this geofence
      geofence:
        $ref: '#/definitions/Geofence'
        description: The geofence information for this landmark
      date:
        type: string
        description: Date associated with the content for this landmark.
  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string