eduapi

package
v0.5.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2026 License: BSD-2-Clause Imports: 10 Imported by: 0

Documentation

Overview

Package eduapi provides an HTTP client for the 1EdTech Edu-API v1.0 specification. Edu-API is a REST/JSON API for accessing student information from Student Information Systems (SIS) such as Ladok.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MergeMaps 

func MergeMaps(maps ...map[string]any) map[string]any

MergeMaps merges multiple flat maps into one. Later maps override earlier ones.

Types

type AcademicSession 

type AcademicSession struct {
	SourcedID    string         `json:"sourcedId"`
	Status       string         `json:"status,omitempty"`
	DateLastMod  string         `json:"dateLastModified,omitempty"`
	Title        string         `json:"title"`
	Type         string         `json:"type"`
	StartDate    string         `json:"startDate"`
	EndDate      string         `json:"endDate"`
	ParentRef    *GUIDRef       `json:"parent,omitempty"`
	ChildrenRefs []GUIDRef      `json:"children,omitempty"`
	SchoolYear   string         `json:"schoolYear,omitempty"`
	Extensions   map[string]any `json:"extensions,omitempty"`
}

AcademicSession represents a term, semester, or academic year.

type AcademicSessionsResponse 

type AcademicSessionsResponse struct {
	AcademicSessions []AcademicSession `json:"academicSessions"`
}

AcademicSessionsResponse represents the Edu-API academic sessions collection response.

type Address 

type Address struct {
	Type          string `json:"type,omitempty"`
	StreetAddress string `json:"streetAddress,omitempty"`
	Locality      string `json:"locality,omitempty"`
	Region        string `json:"region,omitempty"`
	PostalCode    string `json:"postalCode,omitempty"`
	Country       string `json:"country,omitempty"`
}

Address represents a postal address.

type AgentRef 

type AgentRef struct {
	AgentType string  `json:"agentType"`
	PersonRef GUIDRef `json:"person"`
}

AgentRef represents a reference to an agent (advisor, parent, etc.).

type AttributeConfig 

type AttributeConfig struct {
	// Claim is the target claim name (supports dot-notation for nesting)
	Claim string `yaml:"claim" validate:"required"`

	// Required indicates if this attribute must be present
	Required bool `yaml:"required" default:"false"`

	// Transform is an optional transformation to apply
	Transform string `yaml:"transform,omitempty" validate:"omitempty,oneof=lowercase uppercase trim"`

	// Default is an optional default value if attribute is missing
	Default string `yaml:"default,omitempty"`
}

AttributeConfig defines how a single external attribute maps to a credential claim. Mirrors model.AttributeConfig to avoid circular imports.

type AttributeMapping 

type AttributeMapping map[string]AttributeConfig

AttributeMapping maps external attribute names to claim configurations. Mirrors model.AttributeMapping to avoid circular imports between eduapi and model.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is an HTTP client for 1EdTech Edu-API v1.0 endpoints. It handles OAuth 2.0 Client Credentials Grant (CCG) token management.

func NewClient 

func NewClient(cfg ClientConfig, log *logger.Log) (*Client, error)

NewClient creates a new Edu-API client. cfg.TokenCache must be set; the caller is responsible for providing a cache instance.

func (*Client) GetAcademicSession 

func (c *Client) GetAcademicSession(ctx context.Context, sessionID string) (*AcademicSession, error)

GetAcademicSession retrieves an academic session by sourcedId.

func (*Client) GetCourseOffering 

func (c *Client) GetCourseOffering(ctx context.Context, classID string) (*CourseOffering, error)

GetCourseOffering retrieves a single course offering by sourcedId.

func (*Client) GetEnrollmentsForPerson 

func (c *Client) GetEnrollmentsForPerson(ctx context.Context, personID string, opts ...QueryOption) ([]Enrollment, error)

GetEnrollmentsForPerson retrieves all enrollments for a person.

func (*Client) GetOrganization 

func (c *Client) GetOrganization(ctx context.Context, orgID string) (*Organization, error)

GetOrganization retrieves an organization (school) by sourcedId.

func (*Client) GetPerson 

func (c *Client) GetPerson(ctx context.Context, personID string) (*Person, error)

GetPerson retrieves a person by their sourcedId.

func (*Client) GetResultsForPerson 

func (c *Client) GetResultsForPerson(ctx context.Context, personID string, opts ...QueryOption) ([]Result, error)

GetResultsForPerson retrieves all results (grades) for a person.

func (*Client) GetStudents 

func (c *Client) GetStudents(ctx context.Context, opts ...QueryOption) ([]Person, error)

GetStudents retrieves all persons with a student role.

type ClientConfig 

type ClientConfig struct {
	BaseURL      string
	TokenURL     string
	ClientID     string
	ClientSecret string
	Scopes       []string
	Timeout      time.Duration
	TokenCache   cache.Cache[string]
}

ClientConfig holds configuration for creating a new Edu-API client.

type CollectionOffering 

type CollectionOffering struct {
	SourcedID    string         `json:"sourcedId"`
	Status       string         `json:"status,omitempty"`
	DateLastMod  string         `json:"dateLastModified,omitempty"`
	Title        string         `json:"title"`
	OfferingType string         `json:"collectionType,omitempty"`
	SchoolRef    GUIDRef        `json:"school,omitempty"`
	CourseRefs   []GUIDRef      `json:"courses,omitempty"`
	Extensions   map[string]any `json:"extensions,omitempty"`
}

CollectionOffering represents a programme of study (e.g. a degree programme).

type CollectionOfferingsResponse 

type CollectionOfferingsResponse struct {
	CollectionOfferings []CollectionOffering `json:"collectionOfferings"`
}

CollectionOfferingsResponse represents the Edu-API collection offerings (programs) response.

type Config 

type Config struct {
	// Enable turns on Edu-API data source support (default: false)
	Enable bool `yaml:"enable" default:"false"`

	// CredentialTypes lists credential types that can be issued via Edu-API data
	CredentialTypes []string `yaml:"credential_types" validate:"required_if=Enable true,omitempty,min=1"`

	// BaseURL is the base URL of the Edu-API endpoint (e.g. Ladok's Edu-API gateway)
	BaseURL string `yaml:"base_url" validate:"required_if=Enable true" doc_example:"\"https://api.ladok.se/eduapi\""`

	// TokenURL is the OAuth 2.0 token endpoint for Client Credentials Grant
	TokenURL string `yaml:"token_url" validate:"required_if=Enable true" doc_example:"\"https://api.ladok.se/oauth2/token\""`

	// ClientID is the OAuth 2.0 client identifier
	ClientID string `yaml:"client_id" validate:"required_if=Enable true"`

	// ClientSecret is the OAuth 2.0 client secret
	ClientSecret string `yaml:"client_secret" validate:"required_if=Enable true"`

	// Scopes are the OAuth 2.0 scopes to request for the Edu-API
	Scopes []string `yaml:"scopes,omitempty" default:"[\"https://purl.imsglobal.org/spec/or/v1p2/scope/roster-core.readonly\"]"`

	// Timeout is the HTTP client timeout for Edu-API requests
	Timeout time.Duration `yaml:"timeout" default:"10s"`

	// AttributeMappings defines how to map Edu-API data to credential claims.
	// Key: credential type identifier (must match a credential_metadata key).
	AttributeMappings map[string]AttributeMapping `yaml:"attribute_mappings,omitempty"`
}

Config holds the full Edu-API (1EdTech) data source configuration for credential issuance.

func (*Config) ClientConfig 

func (c *Config) ClientConfig() ClientConfig

ClientConfig returns the subset of Config needed by NewClient.

type CourseOffering 

type CourseOffering struct {
	SourcedID    string         `json:"sourcedId"`
	Status       string         `json:"status,omitempty"`
	DateLastMod  string         `json:"dateLastModified,omitempty"`
	Title        string         `json:"title"`
	CourseCode   string         `json:"courseCode,omitempty"`
	ClassType    string         `json:"classType,omitempty"`
	SchoolRef    GUIDRef        `json:"school,omitempty"`
	TermRefs     []GUIDRef      `json:"terms,omitempty"`
	CourseRef    GUIDRef        `json:"course,omitempty"`
	Periods      []string       `json:"periods,omitempty"`
	SubjectCodes []string       `json:"subjectCodes,omitempty"`
	Grades       []string       `json:"grades,omitempty"`
	Extensions   map[string]any `json:"extensions,omitempty"`
}

CourseOffering represents a course offering (class/section) in the Edu-API.

func (*CourseOffering) Flatten 

func (co *CourseOffering) Flatten() map[string]any

Flatten converts a CourseOffering into a flat map.

type CourseOfferingsResponse 

type CourseOfferingsResponse struct {
	CourseOfferings []CourseOffering `json:"courseOfferings"`
}

CourseOfferingsResponse represents the Edu-API course offerings collection response.

type Demographics 

type Demographics struct {
	BirthDate string `json:"birthDate,omitempty"`
	Sex       string `json:"sex,omitempty"`
}

Demographics holds demographic information for a Person.

type Enrollment 

type Enrollment struct {
	SourcedID   string         `json:"sourcedId"`
	Status      string         `json:"status,omitempty"`
	DateLastMod string         `json:"dateLastModified,omitempty"`
	PersonRef   GUIDRef        `json:"user"`
	ClassRef    GUIDRef        `json:"class"`
	Role        string         `json:"role"`
	Primary     bool           `json:"primary,omitempty"`
	BeginDate   string         `json:"beginDate,omitempty"`
	EndDate     string         `json:"endDate,omitempty"`
	Extensions  map[string]any `json:"extensions,omitempty"`
}

Enrollment represents a student enrollment in a class or course section.

func (*Enrollment) Flatten 

func (e *Enrollment) Flatten() map[string]any

Flatten converts an Enrollment into a flat map.

type EnrollmentsResponse 

type EnrollmentsResponse struct {
	Enrollments []Enrollment `json:"enrollments"`
}

EnrollmentsResponse represents the Edu-API enrollments collection response.

type GUIDRef 

type GUIDRef struct {
	SourcedID string `json:"sourcedId"`
	Href      string `json:"href,omitempty"`
	Type      string `json:"type,omitempty"`
}

GUIDRef is a reference by sourcedId and optionally href/type.

type IdentifierEntry 

type IdentifierEntry struct {
	IdentifierType string `json:"identifierType"`
	Identifier     string `json:"identifier"`
}

IdentifierEntry represents an external identifier for a Person.

type LanguageTypedValue 

type LanguageTypedValue struct {
	Value    string `json:"value"`
	Language string `json:"language,omitempty"`
	Type     string `json:"type,omitempty"`
}

LanguageTypedValue represents a value with an associated language tag.

type Organization 

type Organization struct {
	SourcedID    string         `json:"sourcedId"`
	Status       string         `json:"status,omitempty"`
	DateLastMod  string         `json:"dateLastModified,omitempty"`
	Name         string         `json:"name"`
	Type         string         `json:"type,omitempty"`
	Identifier   string         `json:"identifier,omitempty"`
	ParentRef    *GUIDRef       `json:"parent,omitempty"`
	ChildrenRefs []GUIDRef      `json:"children,omitempty"`
	Extensions   map[string]any `json:"extensions,omitempty"`
}

Organization represents an educational institution or unit.

func (*Organization) Flatten 

func (org *Organization) Flatten() map[string]any

Flatten converts an Organization into a flat map.

type OrganizationsResponse 

type OrganizationsResponse struct {
	Organizations []Organization `json:"orgs"`
}

OrganizationsResponse represents the Edu-API organizations collection response.

type Person 

type Person struct {
	SourcedID    string            `json:"sourcedId"`
	Status       string            `json:"status,omitempty"`
	DateLastMod  string            `json:"dateLastModified,omitempty"`
	Name         PersonName        `json:"name"`
	Identifiers  []IdentifierEntry `json:"identifiers,omitempty"`
	Email        []TypedContact    `json:"email,omitempty"`
	Phone        []TypedContact    `json:"phone,omitempty"`
	Address      []Address         `json:"address,omitempty"`
	Demographics *Demographics     `json:"demographics,omitempty"`
	Roles        []Role            `json:"roles,omitempty"`
	Agents       []AgentRef        `json:"agents,omitempty"`
	Extensions   map[string]any    `json:"extensions,omitempty"`
}

Person represents an Edu-API Person entity (1EdTech Edu-API §4.2).

func (*Person) Flatten 

func (p *Person) Flatten() map[string]any

Flatten converts a Person into a flat map suitable for claim transformation.

type PersonName 

type PersonName struct {
	FamilyName    string              `json:"familyName"`
	GivenName     string              `json:"givenName"`
	MiddleName    string              `json:"middleName,omitempty"`
	PreferredName *LanguageTypedValue `json:"preferredName,omitempty"`
	FormattedName *LanguageTypedValue `json:"formattedName,omitempty"`
}

PersonName represents name fields for a Person.

type PersonResponse 

type PersonResponse struct {
	Person Person `json:"person"`
}

PersonResponse represents the Edu-API GET /persons/{personId} response.

type PersonsResponse 

type PersonsResponse struct {
	Persons []Person `json:"persons"`
}

PersonsResponse represents the Edu-API GET /persons (collection) response.

type QueryOption 

type QueryOption func(q url.Values)

QueryOption configures optional query parameters for list endpoints.

func WithFilter 

func WithFilter(filter string) QueryOption

WithFilter adds an Edu-API filter expression.

func WithLimit 

func WithLimit(n int) QueryOption

WithLimit sets the maximum number of results.

func WithOffset 

func WithOffset(n int) QueryOption

WithOffset sets the pagination offset.

func WithOrderBy 

func WithOrderBy(dir string) QueryOption

WithOrderBy sets the sort direction ("asc" or "desc").

func WithSort 

func WithSort(field string) QueryOption

WithSort sets the sort field.

type Result 

type Result struct {
	SourcedID   string         `json:"sourcedId"`
	Status      string         `json:"status,omitempty"`
	DateLastMod string         `json:"dateLastModified,omitempty"`
	PersonRef   GUIDRef        `json:"student"`
	ClassRef    GUIDRef        `json:"lineItem"`
	Score       string         `json:"score,omitempty"`
	ScoreStatus string         `json:"scoreStatus,omitempty"`
	ScoreDate   string         `json:"scoreDate,omitempty"`
	Comment     string         `json:"comment,omitempty"`
	Extensions  map[string]any `json:"extensions,omitempty"`
}

Result represents a grade or score for an enrollment.

func (*Result) Flatten 

func (r *Result) Flatten() map[string]any

Flatten converts a Result into a flat map.

type ResultsResponse 

type ResultsResponse struct {
	Results []Result `json:"results"`
}

ResultsResponse represents the Edu-API results collection response.

type Role 

type Role struct {
	RoleType string  `json:"roleType"`
	Role     string  `json:"role"`
	OrgRef   GUIDRef `json:"org,omitempty"`
}

Role represents a role a person holds within an organization.

type TypedContact 

type TypedContact struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

TypedContact represents a typed contact entry (email/phone).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.