api

Documentation

Overview

Package api provides definitions and functionality related to the API.

Index

• func RequireIDInURI() gin.HandlerFunc
• func RequireMessageIDInURI() gin.HandlerFunc
• func SuccessOrAbort(ctx *gin.Context, code int, err error) bool
• type ApplicationHandler
  • func (h *ApplicationHandler) CreateApplication(ctx *gin.Context)
  • func (h *ApplicationHandler) DeleteApplication(ctx *gin.Context)
  • func (h *ApplicationHandler) GetApplication(ctx *gin.Context)
  • func (h *ApplicationHandler) GetApplications(ctx *gin.Context)
  • func (h *ApplicationHandler) UpdateApplication(ctx *gin.Context)
• type CredentialsManager
• type Database
• type Dispatcher
• type HealthHandler
  • func (h *HealthHandler) Health(ctx *gin.Context)
• type IDInURI
• type NotificationDatabase
• type NotificationDispatcher
• type NotificationHandler
  • func (h *NotificationHandler) CreateNotification(ctx *gin.Context)
  • func (h *NotificationHandler) DeleteNotification(ctx *gin.Context)
• type UserHandler
  • func (h *UserHandler) CreateUser(ctx *gin.Context)
  • func (h *UserHandler) DeleteUser(ctx *gin.Context)
  • func (h *UserHandler) GetUser(ctx *gin.Context)
  • func (h *UserHandler) GetUsers(ctx *gin.Context)
  • func (h *UserHandler) UpdateUser(ctx *gin.Context)

Functions

func RequireIDInURI

func RequireIDInURI() gin.HandlerFunc

RequireIDInURI returns a Gin middleware which requires an ID to be supplied in the URI of the request.

func RequireMessageIDInURI

func RequireMessageIDInURI() gin.HandlerFunc

RequireMessageIDInURI returns a Gin middleware which requires an messageID to be supplied in the URI of the request.

func SuccessOrAbort

func SuccessOrAbort(ctx *gin.Context, code int, err error) bool

SuccessOrAbort is a convenience function to write a HTTP status code based on a given error.

Types

type ApplicationHandler

type ApplicationHandler struct {
	DB Database
	DP Dispatcher
}

ApplicationHandler holds information for processing requests about applications.

func (*ApplicationHandler) CreateApplication

func (h *ApplicationHandler) CreateApplication(ctx *gin.Context)

CreateApplication godoc @Summary Create Application @Description Create a new application @ID post-application @Tags Application @Accept json,mpfd @Produce json @Param name query string true "Name of the application" @Param strict_compatibility query boolean false "Use strict compatibility mode" @Success 200 {object} model.Application @Failure 400 "" @Security BasicAuth @Router /application [post]

func (*ApplicationHandler) DeleteApplication

func (h *ApplicationHandler) DeleteApplication(ctx *gin.Context)

DeleteApplication godoc @Summary Delete Application @Description Delete an application @ID delete-application-id @Tags Application @Accept json,mpfd @Produce json @Param id path int true "ID of the application" @Success 200 "" @Failure 500,404,403 "" @Security BasicAuth @Router /application/{id} [delete]

func (*ApplicationHandler) GetApplication

func (h *ApplicationHandler) GetApplication(ctx *gin.Context)

GetApplication godoc @Summary Get Application @Description Get single application by ID @ID get-application-id @Tags Application @Accept json,mpfd @Produce json @Param id path int true "ID of the application" @Success 200 {object} model.Application @Failure 404,403 "" @Security BasicAuth @Router /application/{id} [get]

func (*ApplicationHandler) GetApplications

func (h *ApplicationHandler) GetApplications(ctx *gin.Context)

GetApplications godoc @Summary Get Applications @Description Get all applications from current user @ID get-application @Tags Application @Accept json,mpfd @Produce json @Success 200 {array} model.Application @Failure 500 "" @Security BasicAuth @Router /application [get]

func (*ApplicationHandler) UpdateApplication

func (h *ApplicationHandler) UpdateApplication(ctx *gin.Context)

UpdateApplication godoc @Summary Update Application @Description Update an application @ID put-application-id @Tags Application @Accept json,mpfd @Produce json @Param id path int true "ID of the application" @Param name query string false "New name for the application" @Param refresh_token query bool false "Generate new refresh token for the application" @Param strict_compatibility query bool false "Whether to use strict compataibility mode" @Success 200 "" @Failure 500,404,403 "" @Security BasicAuth @Router /application/{id} [put]

type CredentialsManager

type CredentialsManager interface {
	CreatePasswordHash(password string) ([]byte, error)
}

The CredentialsManager interface for updating credentials.

type Database

type Database interface {
	Health() error

	CreateApplication(application *model.Application) error
	DeleteApplication(application *model.Application) error
	GetApplicationByID(ID uint) (*model.Application, error)
	GetApplicationByToken(token string) (*model.Application, error)
	UpdateApplication(application *model.Application) error

	AdminUserCount() (int64, error)
	CreateUser(user model.CreateUser) (*model.User, error)
	DeleteUser(user *model.User) error
	GetApplications(user *model.User) ([]model.Application, error)
	GetUserByID(ID uint) (*model.User, error)
	GetUserByName(name string) (*model.User, error)
	GetUsers() ([]model.User, error)
	UpdateUser(user *model.User) error
}

The Database interface for encapsulating database access.

type Dispatcher

type Dispatcher interface {
	RegisterApplication(id uint, name, user string) (string, error)
	DeregisterApplication(a *model.Application, u *model.User) error
	UpdateApplication(a *model.Application, behavior *configuration.RepairBehavior) error
}

The Dispatcher interface for relaying notifications.

type HealthHandler

type HealthHandler struct {
	DB Database
}

HealthHandler holds information for processing requests about the server's health.

func (*HealthHandler) Health

func (h *HealthHandler) Health(ctx *gin.Context)

Health godoc @Summary Health of the application @ID get-health @Tags Health @Accept json,mpfd @Produce json @Success 200 "" @Failure 500 "" @Router /health [get]

type IDInURI

type IDInURI struct {
	ID uint `uri:"id" binding:"required"`
}

IDInURI is used to retrieve an ID from a context.

type NotificationDatabase

type NotificationDatabase interface{}

The NotificationDatabase interface for encapsulating database access.

type NotificationDispatcher

type NotificationDispatcher interface {
	SendNotification(a *model.Application, n *model.Notification) (id string, err error)
	DeleteNotification(a *model.Application, n *model.DeleteNotification) error
}

The NotificationDispatcher interface for relaying notifications.

type NotificationHandler

type NotificationHandler struct {
	DB NotificationDatabase
	DP NotificationDispatcher
}

NotificationHandler holds information for processing requests about notifications.

func (*NotificationHandler) CreateNotification

func (h *NotificationHandler) CreateNotification(ctx *gin.Context)

CreateNotification godoc @Summary Create a Notification @Description Creates a new notification for the given channel @ID post-message @Tags Application @Accept json,mpfd @Produce json @Param message query string true "The message to send" @Param title query string false "The title to send" @Param priority query integer false "The notifications priority" @Param extras query model.NotificationExtras false "JSON object with additional information" @Param token query string true "Channels token, can also be provieded in the header" @Success 200 {object} model.Notification @Failure 500,404,403 "" @Router /message [post]

func (*NotificationHandler) DeleteNotification

func (h *NotificationHandler) DeleteNotification(ctx *gin.Context)

DeleteNotification godoc @Summary Delete a Notification @Description Informs the channel that the notification is deleted @ID deöete-message-id @Tags Application @Accept json,mpfd @Produce json @Param message_id path string true "ID of the message to delete" @Param token query string true "Channels token, can also be provieded in the header" @Success 200 "" @Failure 500,404,403 "" @Router /message/{message_id} [DELETE]

type UserHandler

type UserHandler struct {
	AH *ApplicationHandler
	CM CredentialsManager
	DB Database
	DP Dispatcher
}

UserHandler holds information for processing requests about users.

func (*UserHandler) CreateUser

func (h *UserHandler) CreateUser(ctx *gin.Context)

CreateUser godoc This method assumes that the requesting user has privileges. @Summary Create a User @Description Creates a new user @ID post-user @Tags User @Accept json,mpfd @Produce json @Param name query string true "Name of the user" @Param is_admin query bool false "Whether to set the user as admin or not" @Param matrix_id query string true "Matrix ID of the user in the format @user:domain.tld" @Param password query string true "The users password" @Success 200 {object} model.ExternalUser @Failure 500,404,403 "" @Security BasicAuth @Router /user [post]

func (*UserHandler) DeleteUser

func (h *UserHandler) DeleteUser(ctx *gin.Context)

DeleteUser godoc This method assumes that the requesting user has privileges. @Summary Delete User @Description Delete user @ID delete-user-id @Tags User @Accept json,mpfd @Produce json @Param id path integer true "The users id" @Success 200 "" @Failure 500,404 "" @Security BasicAuth @Router /user/{id} [delete]

func (*UserHandler) GetUser

func (h *UserHandler) GetUser(ctx *gin.Context)

GetUser godoc This method assumes that the requesting user has privileges. @Summary Get User @Description Gets single user @ID get-user-id @Tags User @Accept json,mpfd @Produce json @Param id path integer true "The users id" @Success 200 {object} model.ExternalUser @Failure 500,404 "" @Security BasicAuth @Router /user/{id} [get]

func (*UserHandler) GetUsers

func (h *UserHandler) GetUsers(ctx *gin.Context)

GetUsers godoc This method assumes that the requesting user has privileges. @Summary Get Users @Description Gets a list of all users @ID get-user @Tags User @Accept json,mpfd @Produce json @Success 200 {object} []model.ExternalUser @Failure 500 "" @Security BasicAuth @Router /user [get]

func (*UserHandler) UpdateUser

func (h *UserHandler) UpdateUser(ctx *gin.Context)

UpdateUser godoc This method assumes that the requesting user has privileges. If users can later update their own user, make sure they cannot give themselves privileges. @Summary Update User @Description Update user information @ID put-user-id @Tags User @Accept json,mpfd @Produce json @Param id path integer true "The users id" @Param name query string true "Name of the user" @Param is_admin query bool false "Whether to set the user as admin or not" @Param matrix_id query string true "Matrix ID of the user in the format @user:domain.tld" @Param password query string true "The users password" @Success 200 "" @Failure 500,404,400 "" @Security BasicAuth @Router /user/{id} [put]