PhotonEmitter REST API Overview

PhotonEmitter is a REST Web Service for Photos

Resources

/photos?apiKey&id&tags&geoFrame&sortBy&searchTerm&offset&limit&format

Photos of the PhotonPainter application landscape. A photo belongs to an author.

Methods

GET

Retrieve photo entries metadata. This method is also used to retrieve a single image *file*. For this to work, only one image must be requested.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

The photo's ID. Used for unique identification.

tags

A comma-separated list of terms that the photo is tagged with. The photo must match all of the supplied tags.

geoFrame

string

A rectangular frame of geo coordinates which the image must match. Must have the form of [[minLatitude],[minLongitude],[maxLatitude],[maxLongitude]] (without brackets).

sortBy

One of:

  • title
  • created
  • author
  • rating
  • views

An order criterium for the returned list.

searchTerm

string

A search term for the photo. Searches title and description.

offset

integer

An offset when requesting only a subset of the selected photos. Similar to SQL "LIMIT" use.

limit

integer

A limit for requesting only a subset of the selected photos. Similar to SQL "LIMIT" use.

format

string

One of:

  • xml
  • json
  • img
  • smallimg
  • thumbnail
  • tinyimg
xml

Request photo entries as an XML list.

json

Request photo entries as a JSON list.

img

Request one single photo as binary file. If the given parameters match more than one photo, this request will fail.

smallimg

Requests the photo as a resized version (within 400x400px). If the given parameters match more than one photo, this request will fail.

thumbnail

Requests the photo as a thumbnail version (within 120x120px). If the given parameters match more than one photo, this request will fail.

tinyimg

Requests the photo as a tiny version (within 50x50px). If the given parameters match more than one photo, this request will fail.

available response representations:

PUT

Uploads a new photo to the web service. Only the binary file will be transmitted. In return, an ID is provided, with which the photo's metadata can be added. Without this metadata, the photo is not fully committed.

request query parameters
parameter value description

name

string

The (file)name of the to be submitted photo.

apiKey

string

The API key used to authenticate against the web service.

acceptable request representations:

available response representations:

POST

Updates an existing photo with metadata. Note that all parameters are optional - only the provided ones will be updated.

request query parameters
parameter value description

id

integer

The photo's ID.

apiKey

string

The API key used to authenticate against the web service.

acceptable request representations:

available response representations:

DELETE

Delete a photo entry.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

/users?apiKey&id&username&password&format

Users of the PhotonPainter application landscape.

Methods

GET

Retrieve a single user account. Can either be used with ID to retrieve a unique user or as a combination of username/password, to validate some end user's credentials.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

The user's ID. Used for unique identification.

username

integer

The user's login name. Used to validate an end user's credentials.

password

integer

The user's password. Used to validate an end user's credentials.

format

string

One of:

  • xml
  • json

available response representations:

PUT

Create a new user account.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

acceptable request representations:

available response representations:

DELETE

Delete a user account.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

/comments?apiKey&id&photoId&format

Comments of the PhotonPainter application landscape. A comment belongs to a photo and an author.

Methods

GET

Retrieve a list of comments.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

The comment's ID. Used for unique identification.

photoId

integer

The ID of a photo for which to retrieve the list of comments.

format

string

One of:

  • xml
  • json

available response representations:

PUT

Create a new comment.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

acceptable request representations:

available response representations:

DELETE

Delete a comment.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

/ratings?apiKey&id&photoId&format

Ratings of the PhotonPainter application landscape. A rating belongs to a photo and a submitter.

Methods

GET

Retrieve a list of ratings.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

The rating's ID. Used for unique identification.

photoId

integer

The ID of a photo for which to retrieve the list of ratings.

format

string

One of:

  • xml
  • json

available response representations:

PUT

Create a new rating.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

acceptable request representations:

available response representations:

DELETE

Delete a rating.

request query parameters
parameter value description

apiKey

string

The API key used to authenticate against the web service.

id

integer

/update

Update photos via call of PhotonCollector (currently only as dummy, returns random status).

Methods

GET

Start update.

available response representations:

  • text/plain: boolean (0|1)

Representations

application/xml (pp:photos)

XML Schema

Source: photonpainter.xsd

<element name="photos" type="pp:Photos">
		<annotation>
			<documentation>Contains a list of photos of PhotonPainter.</documentation>
		</annotation>
	</element>

application/json

image/*

image/*

The photo as binary file. Supported formats are JPG and PNG.

text/plain

the URI for the newly created photo.

application/xml (pp:photo)

XML Schema

Source: photonpainter.xsd

<element name="photo" type="pp:Photo">
		<annotation>
			<documentation>Represents one single photo. A photo has some metadata like URI, width, height and creation date, but also contains tags and rating information.</documentation>
		</annotation>
	</element>

application/xml (pp:photo)

XML Schema

Source: photonpainter.xsd

<element name="photo" type="pp:Photo">
		<annotation>
			<documentation>Represents one single photo. A photo has some metadata like URI, width, height and creation date, but also contains tags and rating information.</documentation>
		</annotation>
	</element>

application/xml (pp:user)

XML Schema

Source: photonpainter.xsd

<element name="user" type="pp:User">
		<annotation>
			<documentation>Describes a single user of PhotonPainter.</documentation>
		</annotation>
	</element>

application/json

application/xml (pp:user)

XML Schema

Source: photonpainter.xsd

<element name="user" type="pp:User">
		<annotation>
			<documentation>Describes a single user of PhotonPainter.</documentation>
		</annotation>
	</element>

application/xml (pp:user)

XML Schema

Source: photonpainter.xsd

<element name="user" type="pp:User">
		<annotation>
			<documentation>Describes a single user of PhotonPainter.</documentation>
		</annotation>
	</element>

application/xml (pp:comments)

XML Schema

Source: photonpainter.xsd

<element name="comments" type="pp:Comments">
		<annotation>
			<documentation>Contains a list of comments (typically for one photo).</documentation>
		</annotation>
	</element>

application/json

application/xml (pp:comment)

XML Schema

Source: photonpainter.xsd

<element name="comment" type="pp:Comment">
		<annotation>
			<documentation>Describes a single comment for a photo.</documentation>
		</annotation>
	</element>

application/xml (pp:comment)

XML Schema

Source: photonpainter.xsd

<element name="comment" type="pp:Comment">
		<annotation>
			<documentation>Describes a single comment for a photo.</documentation>
		</annotation>
	</element>

application/xml (pp:ratings)

XML Schema

Source: photonpainter.xsd

<element name="ratings" type="pp:Ratings">
		<annotation>
			<documentation>Contains a list of ratings (typically for one) photo.</documentation>
		</annotation>
	</element>

application/json

application/xml (pp:rating)

XML Schema

Source: photonpainter.xsd

<element name="rating" type="pp:Rating">
		<annotation>
			<documentation>Describes a single user rating for a photo.</documentation>
		</annotation>
	</element>

application/xml (pp:rating)

XML Schema

Source: photonpainter.xsd

<element name="rating" type="pp:Rating">
		<annotation>
			<documentation>Describes a single user rating for a photo.</documentation>
		</annotation>
	</element>