GoSkola24API/README.md

# 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.