Semester resource. Minor documentation update.

README.md

@@ -27,7 +27,7 @@ And then execute:
 
 ```ruby
 # Creates a new instance of client with OAuth2 credentials
-client = KOSapiClient.new(OAUTH_CLIENT_ID, OAUTH_SECRET)
+client = KOSapiClient.new({client_id: OAUTH_CLIENT_ID, client_secret: OAUTH_SECRET})
 
 # Retrieves first page of all course events
 course_events_page = client.course_events
@@ -40,13 +40,38 @@ parallels_page = client.parallels.offset(0).limit(50).query('course.department'
 client.parallels.find(42).related
 ```
 
+## How to extent API functionality
+
+### Add resource
+
+1. Add concrete resource builder to `lib/kosapi_client/resource/`. Use current resources as an inspiration.
+2. Register resource in `lib/kosapi_client/api_client.rb` like:
+
+```ruby
+module KOSapiClient
+
+  class ApiClient
+    include ResourceMapper
+
+    # accessible resources definition
+    resource :courses
+    resource :course_events
+    resource :parallels
+    resource :exams
+    resource :semesters
+    resource :new_resource
+
+    attr_reader :http_client
+	...
+```
+
 ## Configuration
 
 KOSapiClient can be created and configured in two ways.
 The simple way is to call `KOSapiClient.new`, which returns ApiClient instance.
 
 ```ruby
-client = KOSapiClient.new(OAUTH_CLIENT_ID, OAUTH_SECRET)
+client = KOSapiClient.new({client_id: OAUTH_CLIENT_ID, client_secret: OAUTH_SECRET})
 client.parallels.find(42)
 ```
 

lib/kosapi_client/api_client.rb

@@ -8,6 +8,7 @@ class ApiClient
     resource :course_events
     resource :parallels
     resource :exams
+    resource :semesters
 
     attr_reader :http_client
 

lib/kosapi_client/entity.rb

@@ -7,6 +7,7 @@
 require 'kosapi_client/entity/data_mappings'
 require 'kosapi_client/entity/base_entity'
 require 'kosapi_client/entity/result_page'
+require 'kosapi_client/entity/semester'
 require 'kosapi_client/entity/course_event'
 require 'kosapi_client/entity/course'
 require 'kosapi_client/entity/timetable_slot'

lib/kosapi_client/entity/semester.rb

@@ -0,0 +1,11 @@
+module KOSapiClient
+  module Entity
+    class Semester < BaseEntity
+
+      map_data :start_date, Time
+      map_data :end_date, Time
+      map_data :name, MLString
+    end
+  end
+end
+

lib/kosapi_client/request_builder.rb

@@ -37,7 +37,7 @@ def initialize(resource_name, http_client, url_builder = URLBuilder.new(resource
       @http_client = http_client
       @operation = :get
       @body = nil
-      @headers = {}
+      @headers = {'Accept' => 'application/atom+xml'}
       @url_builder = url_builder
       @id = nil
     end

lib/kosapi_client/resource.rb

@@ -3,6 +3,7 @@
 require 'kosapi_client/resource/parallels_builder'
 require 'kosapi_client/resource/exams_builder'
 require 'kosapi_client/resource/course_events_builder'
+require 'kosapi_client/resource/semesters_builder'
 
 module KOSapiClient
   module Resource

lib/kosapi_client/resource/semesters_builder.rb

@@ -0,0 +1,85 @@
+module KOSapiClient
+  module Resource
+    class SemestersBuilder < RequestBuilder
+      ###
+      # Semesters:
+      #   GET /semesters              =>  client.semesters.items
+      #   GET /semesters/{code}       =>  client.semesters.find({code})
+      #   GET /semesters/next         =>  client.semesters.next
+      #   GET /semesters/current      =>  client.semesters.current
+      #
+      # TODO:
+      #   GET /semesters/prev
+      #   GET /semesters/scheduling
+      ###
+
+      ###
+      # GET /semesters
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semesters
+      ##
+      # Example:
+      #   client.semesters.items
+      ###
+
+      ###
+      # GET /semesters/{code}
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/{code}
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semesterscode
+      ##
+      # Example:
+      #   client.semesters.find({code})
+      ###
+
+      ###
+      # GET /semesters/current
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/current
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semesterscurrent
+      ##
+      # Example:
+      #   client.semesters.current
+      ###
+      def current
+        find 'current'
+      end
+
+      ###
+      # GET /semesters/next
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/next
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semestersnext
+      ##
+      # Example:
+      #   client.semesters.next
+      ###
+      def next
+        find 'next'
+      end
+
+      ###
+      # TODO
+      # GET /semesters/prev
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/prev
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semestersprev
+      ##
+      # Example:
+      #
+      ###
+
+      ###
+      # TODO
+      # GET /semesters/scheduling
+      #
+      # URI: https://kosapi.fit.cvut.cz/api/3/semesters/scheduling
+      # @link: https://kosapi.fit.cvut.cz/projects/kosapi/wiki/Semesters#GET-semestersscheduling
+      ##
+      # Example:
+      #
+      ###
+    end
+  end
+end

spec/integration/parallels_spec.rb

@@ -44,7 +44,7 @@
   end
 
   it 'parses timetable slot ID' do
-    page = client.parallels
+    page = client.parallels.query('course.code' => 'MI-PAA')
     slot = page.items.first.timetable_slots.first
     expect(slot.id).not_to be_nil
   end

spec/integration/semesters_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe 'Semesters resource', :vcr, :integration do
+
+  let(:credentials) { { client_id: ENV['KOSAPI_OAUTH_CLIENT_ID'], client_secret: ENV['KOSAPI_OAUTH_CLIENT_SECRET'] } }
+  subject(:client) {  KOSapiClient.new(credentials) }
+
+  it 'fetches semesters list' do
+    page = client.semesters.offset(0).limit(2)
+    expect(page.items.count).to eq 2
+  end
+
+  it 'parses entry ID properly' do
+    page = client.semesters
+    semester = page.items.first
+    expect(semester.id).not_to be_nil
+  end
+
+  it 'parses updated properly' do
+    page = client.semesters
+    semester = page.items.first
+    expect(semester.updated).not_to be_nil
+  end
+
+  it 'parses author properly' do
+    page = client.semesters
+    semester = page.items.first
+    expect(semester.author.name).not_to be_nil
+  end
+
+  it 'parses entry link properly' do
+    page = client.semesters
+    semester = page.items.first
+    expect(semester.link).not_to be_nil
+    expect(semester.link.link_href).not_to be_nil
+    expect(semester.link.link_rel).not_to be_nil
+  end
+
+  it 'fetches current semester' do
+    semester = client.semesters.current
+    expect(semester.start_date).not_to be_nil
+    expect(semester.end_date).not_to be_nil
+
+    expect(Time.new).to be_between(semester.start_date, semester.end_date)
+  end
+
+  it 'fetches next semester' do
+    semester = client.semesters.next
+    expect(semester.start_date).not_to be_nil
+    expect(semester.end_date).not_to be_nil
+
+    expect(Time.new).to be < semester.start_date
+  end
+end