# PhotonEmitter REST API Overview

PhotonEmitter is a REST Web Service for Photos

- Resources
- /photos
- /users
- /comments
- /ratings
- Representations
  - application/xml (pp:photos)
  - application/json
  - image/*
  - image/*
  - text/plain
  - application/xml (pp:photo)
  - application/xml (pp:photo)
  - application/xml (pp:user)
  - application/json
  - application/xml (pp:user)
  - application/xml (pp:user)
  - application/xml (pp:comments)
  - application/json
  - application/xml (pp:comment)
  - application/xml (pp:comment)
  - application/xml (pp:ratings)
  - application/json
  - application/xml (pp:rating)
  - application/xml (pp:rating)

## 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:

- application/xml (pp:photos)
- application/json
- image/*

#### 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:

- image/*

available response representations:

- text/plain

#### 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:

- application/xml (pp:photo)

available response representations:

- application/xml (pp:photo)

#### 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:

- application/xml (pp:user)
- application/json

#### 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:

- application/xml (pp:user)

available response representations:

- application/xml (pp:user)

#### 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:

- application/xml (pp:comments)
- application/json

#### 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:

- application/xml (pp:comment)

available response representations:

- application/xml (pp:comment)

#### 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:

- application/xml (pp:ratings)
- application/json

#### 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:

- application/xml (pp:rating)

available response representations:

- application/xml (pp:rating)

#### DELETE

Delete a rating.

###### request query parameters

parameter | value | description
--- | --- | ---
apiKey | string | The API key used to authenticate against the web service.
id | integer |

## 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/*

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>