PicApport Web-API


The PicApport Web API has been introduced in PicApport Version 7.4

For an example Gallery built with the WebAPI click on the following link: https://en.onlinedemo.picapport.de/public/sharedgalleries.html

The following features are supported:

  • Easy access to photos and their metadata stored in PicApport

  • An function to upload photos to PicApport with setting of metadata like title, tags, description etc…

  • Photos can be dynamically scaled

  • Supports all operators and functions of PicApports built-in photo query language:  https://en.onlinedemo.picapport.de/picapport#help

  • Session and user permission functions are supported including role based photo filtering

Getting started

To get the WebApi up and running we recommend to start with the following configuration parameters in picapport.properties and restart the server:

#the following will work only if a user picapport exists with password picapport (public user)


If everything is configured properly you should see the following in PicApport About-Page (click on the image to enlarge):

URL Scheme


Click on the following example URL to see it working: https://en.onlinedemo.picapport.de/picapportapi/1.0/getSharedGallerys 

Web-interface for tests and examples

PicApport provides an optional Web-interface that can be used to test and play with the API in your own environment: (Or on our Demo: https://en.onlinedemo.picapport.de/picapport-webapitest.html)

Click on the image below to see how it works.

Sample Workflows

Work with shared Photos

Run a Query against PicApports photo database

  1. call createWebApiSession to get a valid apisid (API session ID)
  2. dependent on your configuration it may be required to call authorizeWebApiSession with userid and password to authorize your session
  3. call runQuery to execute you query and get a vid (viewID) and number of photos in the result
  4. call getPhoto, getPhotoMetadata, getThumbnail, getOriginalFile, with apisid, vid and zero based index to access the photos and metadata.

Upload photos

  1. call createWebApiSession to get a valid apisid
  2. dependent on your configuration it may be required to call authorizeWebApiSession with userid and password to authorize your session
  3. call upload to upload photos with metadata

Documentation of available functions

Configuration parameter to control Web-API functions in picapport.properties

For a general description of the picapport.properties see: PicApport-Server Guide

webapi.enablednot set (false)7.4YESThis parameter must be set to true to activate the Web-Api
webapi.testpageenablednot set (true if webapi.enabled)7.4YES

If this parameter is set to false the WebApi-Testpage [http:toServer]/picapport-webapitest.html will not
be available on the PicApport server.

webapi.has.public.contentnot set (false)7.4YESThis parameter must be set to true to activate the delivery of content in the .picapport/public directory.
This can be used to create your own html-files using the Web-Api to create stylish galleys etc.
webapi.public.dir.allowednot set (true if webapi.has.public.content)7.4YES

If this parameter is set to true (default) the the content of the .picapport/public directory can be queried by just entering
the URL [YourPicapportServerAdress]/public

This is only relevant if webapi.has.public.content is set to true.

webapi.functionsnot set (empty)7.4YES

Optional comma separated list of functions that should be available for the web-api.
If this parameter is not defined all functions will be available.

Example to just support access to shared gallery’s:

  • webapi.functions=getSharedGallerys,getGallery,getPhotoMetadata,getPhoto
webapi.apikeynot set (empty)7.4YESOptional parameter to define a key that must be set to call the createWebApiSession
webapi.default.uidnot set (empty)7.4YES

Optional parameter to set a UserID used for the WebAPI session. (technical user)

If set and the uid exists a call to createWebApiSession automaticaly creates
a WebAPI session for this user. In this case a call to authorizeWebApiSession is not required.

Important: userId and password for the user used as webapi.default.uid must be identical!

webapi.session.timeout.secondsnot set (default = 30 * 60 seconds
                         = 30 minutes)

Time until a web-api session on the server will be terminated if no activity detected.

A value of at least 60 seconds must be set

webapi.max.sessions.per.ipnot set (default=20)7.4YES

Maximum number of concurrent open sessions per remote IP-address. It is recommended
to use closeWepApiSession if a session is not required anymore.

A value of at least 1 seconds must be set


Use with care

Optional. Use only for testing in secure networks.

If set to NoPwEncryptionForWebApi then unencryped passwords will be
accepted by the authorizeWebApiSession function.