Very work in progress, yet working [WIP]

app/api/faculties_endpoints.rb

@@ -1,7 +1,9 @@
 require 'api_helper'
 require 'corefines'
 require 'models/semester_day'
-require 'representers/semester_day_representer'
+require 'representers/semester_days_representer'
+require 'representers/semester_weeks_representer'
+require 'sirius_api/semester_schedule'
 
 module API
   class FacultiesEndpoints < Grape::API
@@ -14,14 +16,42 @@ class FacultiesEndpoints < Grape::API
       params { requires :faculty_id, type: Integer, desc: 'Faculty code (5 digits)' }
       route_param :faculty_id do
 
-        resource :days do
+        resource :schedule do
+
+          resource :days do
+            params { use :date_range }
+
+            get do
+              SemesterDaysRepresenter.for_collection.new(
+                SiriusApi::SemesterSchedule.resolve_days(params[:from], params[:to], params[:faculty_id]))
+            end
+
+            params { requires :date, type: Date, desc: 'Date to resolve' }
+            route_param :date do
+              get do
+                SiriusApi::SemesterSchedule.resolve_day(params[:date], params[:faculty_id])
+                  .then { |it| SemesterDaysRepresenter.new(it) }
+                  .else { not_found! }
+              end
+            end
+          end
+
+          resource :weeks do
+            params { use :date_range }
 
-          params { requires :date, type: Date, desc: 'Date to resolve' }
-          route_param :date do
             get do
-              SemesterDay.resolve(params[:date], params[:faculty_id])
-                .then { |it| SemesterDayRepresenter.new(it) }
-                .else { not_found! }
+              SemesterWeeksRepresenter.for_collection.new(
+                SiriusApi::SemesterSchedule.resolve_weeks(params[:from], params[:to], params[:faculty_id]))
+            end
+
+            # TODO: change to year-cweek
+            params { requires :date, type: Date, desc: 'Date to resolve' }
+            route_param :date do
+              get do
+                SiriusApi::SemesterSchedule.resolve_week(params[:date], params[:faculty_id])
+                  .then { |it| SemesterWeeksRepresenter.new(it) }
+                  .else { not_found! }
+              end
             end
           end
         end

app/helpers/api_helper.rb

@@ -18,6 +18,11 @@ module ApiHelper
     optional :offset, type: Integer, min: 0, default: DEFAULT_OFFSET
   end
 
+  params :date_range do
+    optional :from, type: Date, default: Date.today
+    optional :to, type: Date, default: Date.today + 7
+  end
+
   params :username do
     requires :username, type: String, regexp: /\A[a-z0-9]+\z/i, desc: "person's username"
   end

app/models/faculty_semester.rb

@@ -2,6 +2,7 @@
 require 'models/semester_period'
 
 class FacultySemester < Sequel::Model
+  using ::DateRefinements
 
   one_to_many :semester_periods
 
@@ -21,6 +22,23 @@ def self.find_by_date(date, faculty_id)
       .all.first  # eager loading doesn't work with Dataset.first
   end
 
+  ##
+  # @param start_date [Date] date of the first week to return (will be
+  #   rounded to the beginning of the week).
+  # @param end_date [Date] date of the last week to retun (will be rounded to
+  #   the beginning of the week).
+  # @param faculty_id [Fixnum] organizational number of the faculty.
+  # @return [Array<FacultySemester>] faculty semesters that overlap the
+  #   specified date range with attached periods TODO!!!
+  #
+  def self.find_by_date_range_with_periods(start_date, end_date, faculty_id)
+    where('faculty = ? AND (starts_at, ends_at) OVERLAPS (?, ?)',
+          faculty_id, start_date.start_of_week, end_date)
+      .order_by(:starts_at)
+      .eager(semester_periods: ->(ds) { ds.where('starts_at < ?', end_date.end_of_week) } )
+      .all  # <- this is necessary for eager to work correctly!
+  end
+
   def first_week_parity
     Parity.from_numeric(super)
   end

app/models/semester_day.rb

@@ -1,5 +1,6 @@
 require 'day'
 
+# TODO: Move to lib/sirius_api
 class SemesterDay
 
   attr_reader :date, :period, :teaching_week
@@ -48,6 +49,11 @@ def week_parity
     @week_parity = @period.week_parity(@date)
   end
 
+  # @return [FacultySemester]
+  def semester
+    @period.faculty_semester
+  end
+
   def eql?(other)
     %w[class date period teaching_week].all? do |att|
       other.send(att) == self.send(att)

app/models/semester_week.rb

@@ -2,10 +2,11 @@
 require 'date_refinements'
 require 'models/semester_day'
 
+# TODO: Move to lib/sirius_api
 class SemesterWeek
   extend Forwardable
 
-  using Corefines::Object::then
+  using Corefines::Object[:then, :then_if]
   using Corefines::Enumerable::map_by
   using ::DateRefinements
 
@@ -14,16 +15,24 @@ class << self
     # TODO
     #
     # @param semester [FacultySemester]
+    # @param from: [Date, nil] date of the first week to return (will be
+    #   rounded to the beginning of the week).
+    # @param to: [Date, nil] date of the last week to retun (will be rounded to
+    #   the beginning of the week).
     # @return [Array<SemesterWeek>] an array of semester weeks sorted by date.
     #
-    def resolve_weeks(semester)
-      semester.semester_periods
+    def resolve_weeks(semester, from: nil, to: nil)
+      periods_by_week = semester.semester_periods
         .sort_by(&:starts_at)
         .flat_map { |per| index_period_by_weeks per }
+        .then_if(to) { |ary| ary.take_while { |date, _| date <= to } }
         .map_by { |date, per| [date, per] }
+
+      periods_by_week
         .map { |date, pers| SemesterWeek.new(semester, pers, date) }
         .sort_by(&:start_date)
         .tap { |weeks| add_teaching_week_nums! weeks }
+        .drop_while { |week| week.start_date < from if from }
     end
 
     private
@@ -98,7 +107,7 @@ def initialize(semester, periods, start_date, teaching_week = nil)
 
   ##
   # @return [Array<SemesterDay>] an array of semester days inside this week,
-  #   sorted by date from Monday to Sunday.
+  #   sorted by date from Monday to Sunday. The array may contain +nil+ values.
   def days
     @days ||= @start_date.upto(end_date).map { |date|
       @periods.find { |p| p.include? date }.then do |p|

app/representers/semester_days_representer.rb

@@ -0,0 +1,19 @@
+require 'roar/decorator'
+require 'roar/json/json_api'
+
+class SemesterDaysRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI
+
+  type :semester_days
+
+  property :date
+  property :cwday
+  property :period_type, getter: ->(*) { period.type }
+  property :teaching_week
+  property :week_parity
+
+  links do
+    property :semester, getter: ->(*) { "#{semester.faculty}-#{semester.code}" }
+    property :period, getter: ->(*) { period.id }
+  end
+end

app/representers/semester_weeks_representer.rb

@@ -0,0 +1,19 @@
+require 'roar/decorator'
+require 'roar/json/json_api'
+
+class SemesterWeeksRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI
+
+  type :semester_weeks
+
+  property :start_date
+  property :cweek
+  property :period_types
+  property :teaching_week
+  property :week_parity
+
+  links do
+    property :semester, getter: ->(*) { "#{semester.faculty}-#{semester.code}" }
+    collection :periods, getter: ->(*) { periods.map(&:id) }
+  end
+end

docs/Sirius.raml

@@ -43,13 +43,6 @@ traits:
         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:
@@ -83,6 +76,14 @@ resourceTypes:
   - events-collection:
       get:
         is: [ dateScoped, deletable, filterable, includable, paged, secured ]
+        queryParameters:
+          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
         responses:
           200:
             body:
@@ -298,33 +299,80 @@ resourceTypes:
       required: true
       example: BI-PA1
 
-/faculties/{facultyId}/days/{date}:
-  description: Get semester-related parameters for the specified day.
+/faculties/{facultyId}:
   uriParameters:
     facultyId:
       description: Faculty code (5 digits).
       required: true
       example: 18000
-    date:
-      description: The date to resolve.
-      required: true
-      example: 2015-12-22
-  get:
-    responses:
-      200:
-        body:
-          application/json:
-            example: |
-              {
-                "semester_days": {
-                  "date": "2015-12-22",
-                  "semester": "B151",
-                  "period_type": "teaching",
-                  "week_num": 12,
-                  "week_parity": "even",
-                  "week_day": "tuesday"
-                }
-              }
+  /schedule:
+    /days:
+      is: [ dateScoped ]
+      description: Get semester-related parameters for the specified days.
+      get:
+        responses:
+          200:
+            body:
+              application/json:
+      /{date}:
+        description: Get semester-related parameters for the specified day.
+        uriParameters:
+          date:
+            description: The date to resolve.
+            required: true
+            example: 2016-01-06
+        get:
+          responses:
+            200:
+              body:
+                application/json:
+                  example: |
+                    {
+                      "semester_days": {
+                        "date": "2016-01-06",
+                        "cwday": 3,
+                        "period_type": "teaching",
+                        "teaching_week": 13,
+                        "week_parity": "even",
+                        "links": {
+                          "semester": "18000-B151",
+                          "period": 8
+                        }
+                      }
+                    }
+    /weeks:
+      is: [ dateScoped ]
+      description: Get semester-related attributes of the specified weeks.
+      get:
+        responses:
+          200:
+            body:
+              application/json:
+      /{year_cweek}:
+        uriParameters:
+          year_cweek:
+            description: Year and calendar week of the week to resolve.
+            required: true
+            example: 2015-52
+        get:
+          responses:
+            200:
+              body:
+                application/json:
+                  example: |
+                    {
+                      "semester_weeks": {
+                        "start_date": "2015-12-21",
+                        "cweek": 52,
+                        "period_types": [ "teaching", "holiday" ],
+                        "teaching_week": 12,
+                        "week_parity": "even",
+                        "links": {
+                          "semester": "18000-B151",
+                          "periods": [ 5, 6, 7 ]
+                        }
+                      }
+                    }
 
 /schedule_exceptions:
   description: Manage schedule exceptions