337 lines
No EOL
7.6 KiB
Markdown
337 lines
No EOL
7.6 KiB
Markdown
# GoSkola24API
|
|
|
|
Go module for easy interaction with the Skola24 API.
|
|
|
|
The only data you need to use this module is the hostname of your target institution.
|
|
Available hostnames can be found in a list [here](https://www.skola24.se/Applications/Authentication/login.aspx).
|
|
|
|
If you know of a way to get these via API, without scraping, please let me know.
|
|
|
|
Please remember that you can only retrieve data within the currently active hostname/domain.
|
|
|
|
|
|
|
|
# Getting started
|
|
|
|
Install the package in your project:
|
|
|
|
`go get git.zervo.org/zervo/goskola24api`
|
|
|
|
Here is an example of getting all the schools on a host:
|
|
|
|
```golang
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
|
|
GoSkola24API "git.zervo.org/zervo/goskola24api"
|
|
)
|
|
|
|
func main() {
|
|
api := GoSkola24API.Skola24API{
|
|
Host: "avesta.skola24.se",
|
|
}
|
|
|
|
schools, err := api.GetSchools()
|
|
if err != nil {
|
|
fmt.Println("Could not get schools: " + err.Error())
|
|
}
|
|
|
|
for _, school := range schools {
|
|
fmt.Println(school.Name)
|
|
}
|
|
}
|
|
|
|
```
|
|
|
|
The rest of the README is documented examples, as well as information on the available methods and types.
|
|
|
|
Please note that some methods are not strongly typed due to a lack of data to develop against. This is clearly marked by the warnings under the affected methods. If you find a host that provides this data, please let me know.
|
|
|
|
* [Examples](#examples)
|
|
|
|
* [Methods](#methods)
|
|
|
|
* [Types](#types)
|
|
|
|
Good luck! :D
|
|
|
|
|
|
# Examples
|
|
|
|
Here are a few examples of using the module.
|
|
|
|
## Get available terms
|
|
|
|
Get all the available terms (aka semesters) of the host.
|
|
|
|
```golang
|
|
api := GoSkola24API.Skola24API{
|
|
Host: "avesta.skola24.se",
|
|
}
|
|
|
|
terms, err := api.GetTerms()
|
|
if err != nil {
|
|
fmt.Println("Could not get terms: " + err.Error())
|
|
}
|
|
|
|
for _, term := range terms.ActiveTerms {
|
|
fmt.Println(term.Name)
|
|
}
|
|
```
|
|
|
|
## Get teachers in a school
|
|
|
|
Get all teachers in a school.
|
|
|
|
```golang
|
|
api := GoSkola24API.Skola24API{
|
|
Host: "avesta.skola24.se",
|
|
}
|
|
|
|
schools, err := api.GetSchools()
|
|
if err != nil {
|
|
fmt.Println("Could not get schools: " + err.Error())
|
|
}
|
|
|
|
teachers, err := api.GetTeachers(schools[0], true)
|
|
if err != nil {
|
|
fmt.Println("Could not get teachers: " + err.Error())
|
|
}
|
|
|
|
for _, teacher := range teachers {
|
|
fmt.Println(teacher.FullName)
|
|
}
|
|
```
|
|
|
|
|
|
# Methods
|
|
|
|
Here is a list of all available methods, complete with detailed descriptions.
|
|
|
|
## GetTerms() (_result, _error)
|
|
|
|
Retrieves all currently available terms (aka semesters).
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Returns
|
|
|
|
**_result**: < [Terms](#terms) > Holds the retrieved terms data.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
## GetSchools() (_result, _error)
|
|
|
|
Retrieves all available schools.
|
|
|
|
### Parameters
|
|
|
|
None.
|
|
|
|
### Returns
|
|
|
|
**_result**: < [] [School](#school) > Array of available schools.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
## GetRooms(school, checkAvailability) (_result, _error)
|
|
|
|
Retrieves all rooms in a school.
|
|
|
|
### Parameters
|
|
|
|
**school**: < [School](#school) > School to get rooms from.
|
|
|
|
**checkAvailability**: < bool > If stored availability data should be used to skip requests for unavailable data.
|
|
|
|
### Returns
|
|
|
|
**_result**: < [] [Room](#room) > Array of available rooms.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
## GetTeachers(school, checkAvailability) (_result, _error)
|
|
|
|
Retrieves all teachers in a school.
|
|
|
|
### Parameters
|
|
|
|
**school**: < [School](#school) > School to get teachers from.
|
|
|
|
**checkAvailability**: < bool > If stored availability data should be used to skip requests for unavailable data.
|
|
|
|
### Returns
|
|
|
|
**_result**: < [] [Teacher](#teacher) > Array of available teachers.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
## GetStudents(school, checkAvailability) (_result, _error)
|
|
|
|
Retrieves all students in a school.
|
|
|
|
WARNING: Use with caution. I am yet to find a host/school that provides this data, and therefor this method is not typed.
|
|
|
|
### Parameters
|
|
|
|
**school**: < [School](#school) > School to get students from.
|
|
|
|
**checkAvailability**: < bool > If stored availability data should be used to skip requests for unavailable data.
|
|
|
|
### Returns
|
|
|
|
**_result**: < any > Returned student data. WARNING: Types currently unknown.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
## GetClasses(school, checkAvailability) (_result, _error)
|
|
|
|
Retrieves all classes in a school.
|
|
|
|
A class is a group of people, typically taking one or more courses together.
|
|
|
|
### Parameters
|
|
|
|
**school**: < [School](#school) > School to get students from.
|
|
|
|
**checkAvailability**: < bool > If stored availability data should be used to skip requests for unavailable data.
|
|
|
|
### Returns
|
|
|
|
**_result**: < [] [Class](#class) > Array of available classes.
|
|
|
|
**_error**: < error > Holds standard error data if errors were encountered.
|
|
|
|
|
|
|
|
# Types
|
|
|
|
## Terms
|
|
|
|
Holds terms (aka semesters) data.
|
|
|
|
### Fields
|
|
|
|
**ActiveTerms**: < [] [SchoolTerm](#schoolterm) > Array of currently active terms.
|
|
|
|
**UseSchoolYearsFeatures**: < bool > Purpose unknown.
|
|
|
|
## SchoolTerm
|
|
|
|
Represents a school term.
|
|
|
|
### Fields
|
|
|
|
**Start**: < string > Term startdate.
|
|
|
|
**TermId**: < string > ID of the term (GUID).
|
|
|
|
**Name**: < string > Friendlyname of the term.
|
|
|
|
**End**: < string > Term enddate.
|
|
|
|
## School
|
|
|
|
Represents a school.
|
|
|
|
### Fields
|
|
|
|
**Name**: < string > Friendlyname of the school.
|
|
|
|
**SchoolId**: < string > ID of the school (GUID).
|
|
|
|
**HostName**: < string > The hostname / domain the school belongs to.
|
|
|
|
**AllowCalendarExport**: < string > Whether or not school allows traditional calendar export (does not affect exports via this module).
|
|
|
|
**AvailableData**: < [DataAvailability](#dataavailability) > Types of data available for retrieval on the school.
|
|
|
|
## DataAvailability
|
|
|
|
Defines types of data available on a specific entity.
|
|
|
|
### Fields
|
|
|
|
**HasClasses**: < bool > If entity provides classes data.
|
|
|
|
**HasCourses**: < bool > If entity provides courses data.
|
|
|
|
**HasGroups**: < bool > If entity provides groups data.
|
|
|
|
**HasResources**: < bool > If entity provides resources data.
|
|
|
|
**HasRooms**: < bool > If entity provides rooms data.
|
|
|
|
**HasStudents**: < bool > If entity provides students data.
|
|
|
|
**HasSubjects**: < bool > If entity provides teachers data.
|
|
|
|
## Room
|
|
|
|
Represents a room.
|
|
|
|
### Fields
|
|
|
|
**Name**: < string > Friendlyname of the room.
|
|
|
|
**RoomId**: < string > ID of the room (GUID).
|
|
|
|
**External**: < bool > Purpose unknown, but assumed to indicate a room physically isolated from the rest of the school.
|
|
|
|
## Teacher
|
|
|
|
Represents a teacher.
|
|
|
|
### Fields
|
|
|
|
**FirstName**: < string > Teacher's first name.
|
|
|
|
**LastName**: < string > Teacher's last name.
|
|
|
|
**FullName**: < string > Full name (usually firstname+lastname+friendlyid).
|
|
|
|
**FriendlyId**: < string > Friendly/readable ID, usually teacher's initials.
|
|
|
|
**TeacherId**: < string > ID of the teacher (GUID).
|
|
|
|
**IsActive**: < bool > Purpose unknown.
|
|
|
|
**Integrity**: < bool > Purpose unknown.
|
|
|
|
**Reported**: < bool > Purpose unknown.
|
|
|
|
**ReadOnly**: < bool > Purpose unknown.
|
|
|
|
## Class
|
|
|
|
Represents a group of people, usually taking a course together.
|
|
|
|
### Fields
|
|
|
|
**Name**: < string > Friendlyname of the class.
|
|
|
|
**ClassId**: < string > ID of the class (GUID).
|
|
|
|
**AbsenceMessageNotDeliveredCount**: < int > Purpose unknown.
|
|
|
|
**IsResponsible**: < bool > Purpose unknown.
|
|
|
|
**IsClass**: < bool > Purpose unknown.
|
|
|
|
**IsAdmin**: < bool > Purpose unknown.
|
|
|
|
**IsPrincipal**: < bool > Purpose unknown.
|
|
|
|
**IsMentor**: < bool > Purpose unknown.
|
|
|
|
**IsPreschoolGroup**: < bool > Purpose unkown.
|
|
|
|
**Teachers**: < any > Teachers, typically mentors, for the class. WARNING: Currently untyped, use with caution.
|
|
|
|
**SubstituteTeacherId**: < any > Teacher ID of substitute teacher (if any). See [Teacher](#teacher).
|
|
|
|
**TeacherChangeStudents**: < int > Purpose unknown. |