api

package
Version: v0.0.0-...-fd27f88 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2022 License: AGPL-3.0 Imports: 42 Imported by: 0

Documentation

Overview

Package api provides REST API request handlers.

Copyright (c) 2018 - 2022 PhotoPrism UG. All rights reserved.

This program is free software: you can redistribute it and/or modify
it under Version 3 of the GNU Affero General Public License (the "AGPL"):
<https://docs.photoprism.app/license/agpl>

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

The AGPL is supplemented by our Trademark and Brand Guidelines,
which describe how our Brand Assets may be used:
<https://photoprism.app/trademark>

Feel free to send an email to hello@photoprism.app if you have questions, want to support our work, or just want to say hello.

Additional information can be found in our Developer Guide: <https://docs.photoprism.app/developer-guide/>

Index

Constants

View Source
const (
	ContentTypeAvc = `video/mp4; codecs="avc1"`
)

Variables

This section is empty.

Functions

func Abort

func Abort(c *gin.Context, code int, id i18n.Message, params ...interface{})

func AbortAlbumNotFound

func AbortAlbumNotFound(c *gin.Context)

func AbortAlreadyExists

func AbortAlreadyExists(c *gin.Context, s string)

func AbortBadRequest

func AbortBadRequest(c *gin.Context)

func AbortBusy

func AbortBusy(c *gin.Context)

func AbortDeleteFailed

func AbortDeleteFailed(c *gin.Context)

func AbortEntityNotFound

func AbortEntityNotFound(c *gin.Context)

func AbortFeatureDisabled

func AbortFeatureDisabled(c *gin.Context)

func AbortSaveFailed

func AbortSaveFailed(c *gin.Context)

func AbortUnauthorized

func AbortUnauthorized(c *gin.Context)

func AbortUnexpected

func AbortUnexpected(c *gin.Context)

func AddCacheHeader

func AddCacheHeader(c *gin.Context, maxAge MaxAge)

AddCacheHeader adds a cache control header to the response.

func AddContentTypeHeader

func AddContentTypeHeader(c *gin.Context, contentType string)

AddContentTypeHeader adds a content type header to the response.

func AddCountHeader

func AddCountHeader(c *gin.Context, count int)

AddCountHeader adds the actual result count to the response.

func AddCoverCacheHeader

func AddCoverCacheHeader(c *gin.Context)

AddCoverCacheHeader adds cover image cache control headers to the response.

func AddDownloadHeader

func AddDownloadHeader(c *gin.Context, fileName string)

AddDownloadHeader adds a header indicating the response is expected to be downloaded.

func AddFileCountHeaders

func AddFileCountHeaders(c *gin.Context, filesCount, foldersCount int)

AddFileCountHeaders adds file and folder counts to the response.

func AddLimitHeader

func AddLimitHeader(c *gin.Context, limit int)

AddLimitHeader adds the max result count to the response.

func AddOffsetHeader

func AddOffsetHeader(c *gin.Context, offset int)

AddOffsetHeader adds the result offset to the response.

func AddPhotoLabel

func AddPhotoLabel(router *gin.RouterGroup)

POST /api/v1/photos/:uid/label

Parameters:

uid: string PhotoUID as returned by the API

func AddPhotosToAlbum

func AddPhotosToAlbum(router *gin.RouterGroup)

AddPhotosToAlbum adds photos to an album.

POST /api/v1/albums/:uid/photos

func AddSessionHeader

func AddSessionHeader(c *gin.Context, id string)

AddSessionHeader adds a session id header to the response.

func AddThumbCacheHeader

func AddThumbCacheHeader(c *gin.Context)

AddThumbCacheHeader adds thumbnail cache control headers to the response.

func AddTokenHeaders

func AddTokenHeaders(c *gin.Context)

AddTokenHeaders adds preview token headers to the response.

func AlbumCover

func AlbumCover(router *gin.RouterGroup)

AlbumCover returns an album cover image.

GET /api/v1/albums/:uid/t/:token/:size

Parameters:

uid: string album uid
token: string security token (see config)
size: string thumb type, see photoprism.ThumbnailTypes

func ApprovePhoto

func ApprovePhoto(router *gin.RouterGroup)

POST /api/v1/photos/:uid/approve

Parameters:

uid: string PhotoUID as returned by the API

func Auth

func Auth(id string, resource acl.Resource, action acl.Action) session.Data

Auth returns the session if user is authorized for the current action.

func BatchAlbumsDelete

func BatchAlbumsDelete(router *gin.RouterGroup)

BatchAlbumsDelete permanently removes multiple albums.

POST /api/v1/batch/albums/delete

func BatchLabelsDelete

func BatchLabelsDelete(router *gin.RouterGroup)

BatchLabelsDelete deletes multiple labels.

POST /api/v1/batch/labels/delete

func BatchPhotosApprove

func BatchPhotosApprove(router *gin.RouterGroup)

BatchPhotosApprove approves multiple photos that are currently under review.

POST /api/v1/batch/photos/approve

func BatchPhotosArchive

func BatchPhotosArchive(router *gin.RouterGroup)

BatchPhotosArchive moves multiple photos to the archive.

POST /api/v1/batch/photos/archive

func BatchPhotosDelete

func BatchPhotosDelete(router *gin.RouterGroup)

BatchPhotosDelete permanently removes multiple photos from the archive.

POST /api/v1/batch/photos/delete

func BatchPhotosPrivate

func BatchPhotosPrivate(router *gin.RouterGroup)

BatchPhotosPrivate flags multiple photos as private.

POST /api/v1/batch/photos/private

func BatchPhotosRestore

func BatchPhotosRestore(router *gin.RouterGroup)

BatchPhotosRestore restores multiple photos from the archive.

POST /api/v1/batch/photos/restore

func CacheKey

func CacheKey(ns, uid, name string) string

CacheKey returns a cache key string based on namespace, uid and name.

func CancelImport

func CancelImport(router *gin.RouterGroup)

CancelImport stops the current import operation.

DELETE /api/v1/import

func CancelIndexing

func CancelIndexing(router *gin.RouterGroup)

CancelIndexing stops indexing media files in the "originals" folder.

DELETE /api/v1/index

func ChangePassword

func ChangePassword(router *gin.RouterGroup)

PUT /api/v1/users/:uid/password

func ClearMarkerSubject

func ClearMarkerSubject(router *gin.RouterGroup)

ClearMarkerSubject removes an existing marker subject association.

DELETE /api/v1/markers/:marker_uid/subject

Parameters:

uid: string Photo UID as returned by the API
file_uid: string File UID as returned by the API
id: int Marker ID as returned by the API

func CloneAlbums

func CloneAlbums(router *gin.RouterGroup)

CloneAlbums creates a new album containing pictures from other albums.

POST /api/v1/albums/:uid/clone

func Connect

func Connect(router *gin.RouterGroup)

Connect confirms external service accounts using a token.

PUT /api/v1/connect/:name

func CreateAccount

func CreateAccount(router *gin.RouterGroup)

CreateAccount creates a new remote account configuration.

POST /api/v1/accounts

func CreateAlbum

func CreateAlbum(router *gin.RouterGroup)

CreateAlbum adds a new album.

POST /api/v1/albums

func CreateAlbumLink(router *gin.RouterGroup)

POST /api/v1/albums/:uid/links

func CreateLabelLink(router *gin.RouterGroup)

POST /api/v1/labels/:uid/links

func CreateLink(c *gin.Context)

CreateLink returns a new link entity initialized with request data

func CreatePhotoLink(router *gin.RouterGroup)

POST /api/v1/photos/:uid/links

func CreateSession

func CreateSession(router *gin.RouterGroup)

POST /api/v1/session

func DeleteAccount

func DeleteAccount(router *gin.RouterGroup)

DeleteAccount removes a remote account configuration.

DELETE /api/v1/accounts/:id

Parameters:

id: string Account ID as returned by the API

func DeleteAlbum

func DeleteAlbum(router *gin.RouterGroup)

DeleteAlbum deletes an existing album.

DELETE /api/v1/albums/:uid

func DeleteAlbumLink(router *gin.RouterGroup)

DELETE /api/v1/albums/:uid/links/:link

func DeleteErrors

func DeleteErrors(router *gin.RouterGroup)

DeleteErrors removes all entries from the error logs.

DELETE /api/v1/errors

func DeleteFile

func DeleteFile(router *gin.RouterGroup)

DeleteFile removes a file from storage. DELETE /api/v1/photos/:uid/files/:file_uid

Parameters:

uid: string Photo UID as returned by the API
file_uid: string File UID as returned by the API
func DeleteLabelLink(router *gin.RouterGroup)

DELETE /api/v1/labels/:uid/links/:link

func DeleteLink(c *gin.Context)

DELETE /api/v1/:entity/:uid/links/:link

func DeletePhotoLink(router *gin.RouterGroup)

DELETE /api/v1/photos/:uid/links/:link

func DeleteSession

func DeleteSession(router *gin.RouterGroup)

DELETE /api/v1/session/:id

func DislikeAlbum

func DislikeAlbum(router *gin.RouterGroup)

DislikeAlbum removes the favorite flag from an album.

DELETE /api/v1/albums/:uid/like

Parameters:

uid: string Album UID

func DislikeLabel

func DislikeLabel(router *gin.RouterGroup)

DislikeLabel removes the favorite flag from a label.

DELETE /api/v1/labels/:uid/like

Parameters:

uid: string Label UID

func DislikePhoto

func DislikePhoto(router *gin.RouterGroup)

DELETE /api/v1/photos/:uid/like

Parameters:

uid: string PhotoUID as returned by the API

func DislikeSubject

func DislikeSubject(router *gin.RouterGroup)

DislikeSubject removes the favorite flag from a subject.

DELETE /api/v1/subjects/:uid/like

Parameters:

uid: string Subject UID

func DownloadAlbum

func DownloadAlbum(router *gin.RouterGroup)

DownloadAlbum streams the album contents as zip archive.

GET /api/v1/albums/:uid/dl

func DownloadName

func DownloadName(c *gin.Context) entity.DownloadName

DownloadName returns the download file name type.

func Error

func Error(c *gin.Context, code int, err error, id i18n.Message, params ...interface{})

func FlushCoverCache

func FlushCoverCache()

FlushCoverCache clears the complete cover cache.

func FolderCover

func FolderCover(router *gin.RouterGroup)

FolderCover returns a folder cover image.

GET /api/v1/folders/t/:hash/:token/:size

Parameters:

uid: string folder uid
token: string url security token, see config
size: string thumb type, see thumb.Sizes

func GetAccount

func GetAccount(router *gin.RouterGroup)

GetAccount returns an account as JSON.

GET /api/v1/accounts/:id

Parameters:

id: string Account ID as returned by the API

func GetAccountFolders

func GetAccountFolders(router *gin.RouterGroup)

GetAccountFolders returns folders that belong to an account as JSON.

GET /api/v1/accounts/:id/folders

Parameters:

id: string Account ID as returned by the API

func GetAlbum

func GetAlbum(router *gin.RouterGroup)

GetAlbum returns album details as JSON.

GET /api/v1/albums/:uid

func GetAlbumLinks(router *gin.RouterGroup)

GET /api/v1/albums/:uid/links

func GetConfig

func GetConfig(router *gin.RouterGroup)

GetConfig returns client config values.

GET /api/v1/config

func GetConfigOptions

func GetConfigOptions(router *gin.RouterGroup)

GetConfigOptions returns backend config options.

GET /api/v1/config/options

func GetDownload

func GetDownload(router *gin.RouterGroup)

GetDownload returns the raw file data.

GET /api/v1/dl/:hash

Parameters:

hash: string The file hash as returned by the files/photos endpoint

func GetErrors

func GetErrors(router *gin.RouterGroup)

GetErrors searches the error logs and returns the results as JSON.

GET /api/v1/errors

func GetFace

func GetFace(router *gin.RouterGroup)

GetFace returns a face as JSON.

GET /api/v1/faces/:id

func GetFile

func GetFile(router *gin.RouterGroup)

GetFile returns file details as JSON.

Route: GET /api/v1/files/:hash Params: - hash (string) SHA-1 hash of the file

func GetLabelLinks(router *gin.RouterGroup)

GET /api/v1/labels/:uid/links

func GetMomentsTime

func GetMomentsTime(router *gin.RouterGroup)

GET /api/v1/moments/time

func GetPhoto

func GetPhoto(router *gin.RouterGroup)

GetPhoto returns photo details as JSON.

Route : GET /api/v1/photos/:uid Params: - uid (string) PhotoUID as returned by the API

func GetPhotoDownload

func GetPhotoDownload(router *gin.RouterGroup)

GetPhotoDownload returns the primary file matching that belongs to the photo.

Route :GET /api/v1/photos/:uid/dl Params: - uid (string) PhotoUID as returned by the API

func GetPhotoLinks(router *gin.RouterGroup)

GET /api/v1/photos/:uid/links

func GetPhotoYaml

func GetPhotoYaml(router *gin.RouterGroup)

GET /api/v1/photos/:uid/yaml

Parameters:

uid: string PhotoUID as returned by the API

func GetSettings

func GetSettings(router *gin.RouterGroup)

GET /api/v1/settings

func GetStatus

func GetStatus(router *gin.RouterGroup)

GET /api/v1/status

func GetSubject

func GetSubject(router *gin.RouterGroup)

GetSubject returns a subject as JSON.

GET /api/v1/subjects/:uid

func GetSvg

func GetSvg(router *gin.RouterGroup)

GET /api/v1/svg/*

func GetThumb

func GetThumb(router *gin.RouterGroup)

GetThumb returns a thumbnail image matching the file hash, crop area, and type.

GET /api/v1/t/:thumb/:token/:size

Parameters:

thumb: string sha1 file hash plus optional crop area
token: string url security token, see config
size: string thumb type, see thumb.Sizes

func GetVideo

func GetVideo(router *gin.RouterGroup)

GetVideo streams videos.

GET /api/v1/videos/:hash/:token/:type

Parameters:

hash: string The photo or video file hash as returned by the search API
type: string Video format

func InvalidDownloadToken

func InvalidDownloadToken(c *gin.Context) bool

InvalidDownloadToken returns true if the token is invalid.

func InvalidPreviewToken

func InvalidPreviewToken(c *gin.Context) bool

InvalidPreviewToken returns true if the token is invalid.

func LabelCover

func LabelCover(router *gin.RouterGroup)

LabelCover returns a label cover image.

GET /api/v1/labels/:uid/t/:token/:size

Parameters:

uid: string label uid
token: string security token (see config)
size: string thumb type, see photoprism.ThumbnailTypes

func LikeAlbum

func LikeAlbum(router *gin.RouterGroup)

LikeAlbum sets the favorite flag for an album.

POST /api/v1/albums/:uid/like

Parameters:

uid: string Album UID

func LikeLabel

func LikeLabel(router *gin.RouterGroup)

LikeLabel flags a label as favorite.

POST /api/v1/labels/:uid/like

Parameters:

uid: string Label UID

func LikePhoto

func LikePhoto(router *gin.RouterGroup)

POST /api/v1/photos/:uid/like

Parameters:

uid: string PhotoUID as returned by the API

func LikeSubject

func LikeSubject(router *gin.RouterGroup)

LikeSubject flags a subject as favorite.

POST /api/v1/subjects/:uid/like

Parameters:

uid: string Subject UID

func PhotoPrimary

func PhotoPrimary(router *gin.RouterGroup)

POST /api/v1/photos/:uid/files/:file_uid/primary

Parameters:

uid: string PhotoUID as returned by the API
file_uid: string File UID as returned by the API

func PhotoUnstack

func PhotoUnstack(router *gin.RouterGroup)

PhotoUnstack removes a file from an existing photo stack.

POST /api/v1/photos/:uid/files/:file_uid/unstack

Parameters:

uid: string Photo UID as returned by the API
file_uid: string File UID as returned by the API

func PublishAlbumEvent

func PublishAlbumEvent(e EntityEvent, uid string, c *gin.Context)

func PublishLabelEvent

func PublishLabelEvent(e EntityEvent, uid string, c *gin.Context)

func PublishPhotoEvent

func PublishPhotoEvent(e EntityEvent, uid string, c *gin.Context)

func PublishSubjectEvent

func PublishSubjectEvent(e EntityEvent, uid string, c *gin.Context)

func RemoveFromAlbumCoverCache

func RemoveFromAlbumCoverCache(uid string)

RemoveFromAlbumCoverCache removes covers by album UID e.g. after adding or removing photos.

func RemoveFromFolderCache

func RemoveFromFolderCache(rootName string)

RemoveFromFolderCache removes an item from the folder cache e.g. after indexing.

func RemovePhotoLabel

func RemovePhotoLabel(router *gin.RouterGroup)

DELETE /api/v1/photos/:uid/label/:id

Parameters:

uid: string PhotoUID as returned by the API
id: int LabelId as returned by the API

func RemovePhotosFromAlbum

func RemovePhotosFromAlbum(router *gin.RouterGroup)

RemovePhotosFromAlbum removes photos from an album.

DELETE /api/v1/albums/:uid/photos

func SaveAlbumAsYaml

func SaveAlbumAsYaml(a entity.Album)

SaveAlbumAsYaml saves album data as YAML file.

func SaveConfigOptions

func SaveConfigOptions(router *gin.RouterGroup)

SaveConfigOptions updates backend config options.

POST /api/v1/config/options

func SavePhotoAsYaml

func SavePhotoAsYaml(p entity.Photo)

SavePhotoAsYaml saves photo data as YAML file.

func SaveSettings

func SaveSettings(router *gin.RouterGroup)

POST /api/v1/settings

func SearchAccounts

func SearchAccounts(router *gin.RouterGroup)

SearchAccounts finds accounts and returns them as JSON.

GET /api/v1/accounts

func SearchAlbums

func SearchAlbums(router *gin.RouterGroup)

SearchAlbums finds albums and returns them as JSON.

GET /api/v1/albums

func SearchFaces

func SearchFaces(router *gin.RouterGroup)

SearchFaces finds and returns faces as JSON.

GET /api/v1/faces

func SearchFolders

func SearchFolders(router *gin.RouterGroup, urlPath, rootName, rootPath string)

SearchFolders is a reusable request handler for directory listings (GET /api/v1/folders/*).

func SearchFoldersImport

func SearchFoldersImport(router *gin.RouterGroup)

SearchFoldersImport returns import folders as JSON.

GET /api/v1/folders/import

func SearchFoldersOriginals

func SearchFoldersOriginals(router *gin.RouterGroup)

SearchFoldersOriginals returns folders in originals as JSON.

GET /api/v1/folders/originals

func SearchGeo

func SearchGeo(router *gin.RouterGroup)

SearchGeo finds photos and returns results as JSON, so they can be displayed on a map or in a viewer.

GET /api/v1/geo

See form.SearchPhotosGeo for supported search params and data types.

func SearchLabels

func SearchLabels(router *gin.RouterGroup)

SearchLabels finds and returns labels as JSON.

GET /api/v1/labels

func SearchPhotos

func SearchPhotos(router *gin.RouterGroup)

SearchPhotos searches the pictures index and returns the result as JSON.

GET /api/v1/photos

See form.SearchPhotos for supported search params and data types.

func SearchSubjects

func SearchSubjects(router *gin.RouterGroup)

SearchSubjects finds and returns subjects as JSON.

GET /api/v1/subjects

func SendFeedback

func SendFeedback(router *gin.RouterGroup)

SendFeedback sends a feedback message.

POST /api/v1/feedback

func Session

func Session(id string) session.Data

Session returns the current session data.

func SessionID

func SessionID(c *gin.Context) string

Gets session id from HTTP header.

func SharePreview

func SharePreview(router *gin.RouterGroup)

SharePreview returns a link share preview image.

GET /s/:token/:uid/preview TODO: Proof of concept, needs refactoring.

func ShareWithAccount

func ShareWithAccount(router *gin.RouterGroup)

ShareWithAccount uploads files to the selected account.

GET /api/v1/accounts/:id/share

Parameters:

id: string Account ID as returned by the API

func Shares

func Shares(router *gin.RouterGroup)

GET /s/:token/...

func StartImport

func StartImport(router *gin.RouterGroup)

StartImport imports media files from a directory and converts/indexes them as needed.

POST /api/v1/import*

func StartIndexing

func StartIndexing(router *gin.RouterGroup)

StartIndexing indexes media files in the "originals" folder.

POST /api/v1/index

func UpdateAccount

func UpdateAccount(router *gin.RouterGroup)

UpdateAccount updates a remote account configuration.

PUT /api/v1/accounts/:id

Parameters:

id: string Account ID as returned by the API

func UpdateAlbum

func UpdateAlbum(router *gin.RouterGroup)

UpdateAlbum updates album metadata like title and description.

PUT /api/v1/albums/:uid

func UpdateAlbumLink(router *gin.RouterGroup)

PUT /api/v1/albums/:uid/links/:link

func UpdateClientConfig

func UpdateClientConfig()

func UpdateFace

func UpdateFace(router *gin.RouterGroup)

UpdateFace updates face properties.

PUT /api/v1/faces/:id

func UpdateLabel

func UpdateLabel(router *gin.RouterGroup)

UpdateLabel updates label properties.

PUT /api/v1/labels/:uid

func UpdateLabelLink(router *gin.RouterGroup)

PUT /api/v1/labels/:uid/links/:link

func UpdateLink(c *gin.Context)

PUT /api/v1/:entity/:uid/links/:link

func UpdateMarker

func UpdateMarker(router *gin.RouterGroup)

UpdateMarker updates an existing file marker e.g. representing a face.

PUT /api/v1/markers/:marker_uid

Parameters:

uid: string Photo UID as returned by the API
file_uid: string File UID as returned by the API
id: int Marker ID as returned by the API

func UpdatePhoto

func UpdatePhoto(router *gin.RouterGroup)

UpdatePhoto updates photo details and returns them as JSON.

PUT /api/v1/photos/:uid

func UpdatePhotoLabel

func UpdatePhotoLabel(router *gin.RouterGroup)

PUT /api/v1/photos/:uid/label/:id

Parameters:

uid: string PhotoUID as returned by the API
id: int LabelId as returned by the API
func UpdatePhotoLink(router *gin.RouterGroup)

PUT /api/v1/photos/:uid/links/:link

func UpdateSubject

func UpdateSubject(router *gin.RouterGroup)

UpdateSubject updates subject properties.

PUT /api/v1/subjects/:uid

func Upload

func Upload(router *gin.RouterGroup)

POST /api/v1/upload/:path

func Websocket

func Websocket(router *gin.RouterGroup)

Websocket registers websocket request handler.

GET /api/v1/ws

func ZipCreate

func ZipCreate(router *gin.RouterGroup)

ZipCreate creates a zip file archive for download.

POST /api/v1/zip

func ZipDownload

func ZipDownload(router *gin.RouterGroup)

ZipDownload downloads a zip file archive.

GET /api/v1/zip/:filename

Types

type ByteCache

type ByteCache struct {
	Data []byte
}

type EntityEvent

type EntityEvent string
const (
	EntityUpdated EntityEvent = "updated"
	EntityCreated EntityEvent = "created"
	EntityDeleted EntityEvent = "deleted"
)

type FoldersResponse

type FoldersResponse struct {
	Root      string          `json:"root,omitempty"`
	Folders   []entity.Folder `json:"folders"`
	Files     []entity.File   `json:"files,omitempty"`
	Recursive bool            `json:"recursive,omitempty"`
	Cached    bool            `json:"cached,omitempty"`
}

FoldersResponse represents the folders API response.

type MaxAge

type MaxAge int

MaxAge represents a cache TTL in seconds.

var (
	CoverCacheTTL MaxAge = 3600           // 1 hour
	ThumbCacheTTL MaxAge = 3600 * 24 * 90 // ~ 3 months
)

Default cache TTL times in seconds.

func (MaxAge) String

func (a MaxAge) String() string

String returns the cache TTL in seconds as string.

type ThumbCache

type ThumbCache struct {
	FileName  string
	ShareName string
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL