ABQ Film Tour Backend

HTTPS://jscpeterson.com/rest/

Documentation for the RESTful API for ABQ Film Tour

Version 0.1.1

APIs

Path	Method	Summary
/film_locations
	GET	Gets all film locations.
	POST	Posts a new film location.
	PATCH	Modifies a film location.
/film_locations/{filmLocationId}
	GET	Gets a film location.
	DELETE	Deletes a film location.
/film_locations/{filmLocationId}/images
	GET	Gets all images for a location.
	POST	Posts a new image.
/film_locations/{filmLocationId}/images/
	PATCH	Modifies an image.
/film_locations/{filmLocationId}/images/{imageId}
	GET	Gets an image.
	DELETE	Deletes an image.
/film_locations/{filmLocationId}/user_comments
	GET	Gets all user comments for a location.
	POST	Posts a new user comment.
	PATCH	Modifies a user comment.
/film_locations/{filmLocationId}/user_comments/{userCommentId}
	GET	Gets a user comment.
	DELETE	Deletes a user comment.
/images
	GET	Gets all images.
	POST	Posts a new image.
/images/{imageId}
	GET	Gets an image.
	DELETE	Deletes an image.
/productions
	GET	Gets all productions/
	POST	Posts a new production.
	PATCH	Modifies a production.
/productions/{productionId}
	GET	Gets a single production.
	DELETE	Deletes a production.
/productions/{productionId}/poster
	GET	Retrieves a poster image for the production.
/user_comments
	GET	Gets all user comments.
	POST	Posts a new user comment.
/user_comments/{userCommentId}
	DELETE	Modifies a user comment.
/user_comments/{user_comments}
	GET	Deletes a user comment.
/users
	GET	Gets all users.
	POST	Posts a new user.
	PATCH	Modifies a user.
/users/{userId}
	GET	Gets a single user.
	DELETE	Deletes a user.
/users/{userId}/film_locations
	GET	Gets all locations submitted by a user.
/users/{userId}/images
	GET	Gets all images submitted by a user.
/users/{userId}/user_comments
	GET	Gets all comments submitted by a user.

/film_locations

GET

Gets all film locations.

Gets all film locations, ordered by the time of creation.

Request

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[FilmLocation]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new film location.

Posts a new film location to the film locations endpoint. Should include coordinates, a site name, a Google ID, Google name, profile picture URL, and an associated Production at the minimum.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			FilmLocation

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	FilmLocation
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

PATCH

Modifies a film location.

Restricted to superuser privileges or above. Patches a film location. All data will be overwritten - current fields to stay the same must be included as well. The ID of the image should be included in the body. Can be used to approve a location submission.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			FilmLocation

Response

Status Code	Reason	Response Model
200	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/film_locations/{filmLocationId}

GET

Gets a film location.

Gets a single film location by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	FilmLocation
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

DELETE

Deletes a film location.

Restricted to superuser privileges or above. Deletes a film location by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/film_locations/{filmLocationId}/images

GET

Gets all images for a location.

Gets all of the images on a film location endpoint, ordered by the time of creation.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[Image]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new image.

Posts a new image to a film location endpoint. Should contain a Google ID, Google name, and profile picture URL for the submitter and the URL the image is located at.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			Image
filmLocationId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Image
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

/film_locations/{filmLocationId}/images/

PATCH

Modifies an image.

Restricted to superuser privileges or above. Patches an image from the images endpoint on a film location. All data will be overwritten - current fields to stay the same must be included as well. The ID of the image should be included in the body. Can be used to approve an image submission.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
body	body	no			Image

Response

Status Code	Reason	Response Model
200	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/film_locations/{filmLocationId}/images/{imageId}

GET

Gets an image.

Gets a single image on a film location endpoint, referenced by its internal ID

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
imageId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Image
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

DELETE

Deletes an image.

Restricted to superuser privileges or above. Deletes a single image on a film location endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
imageId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/film_locations/{filmLocationId}/user_comments

GET

Gets all user comments for a location.

Gets all of the user comments on a film location endpoint, ordered by the time of creation.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[UserComment]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new user comment.

Posts a new user comment to a film location endpoint. Should contain a Google ID, Google name, and profile picture URL for the author and the text content of the comment.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			UserComment
filmLocationId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	UserComment
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

PATCH

Modifies a user comment.

Restricted to superuser privileges or above. Patches a user comment from the user comments endpoint on a film location. All data will be overwritten - current fields to stay the same must be included as well. The ID of the user comment should be included in the body. Can be used to approve a comment submission.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
body	body	no			UserComment

Response

Status Code	Reason	Response Model
200	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/film_locations/{filmLocationId}/user_comments/{userCommentId}

GET

Gets a user comment.

Gets a single user comment, referenced by its internal ID

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
userCommentId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	UserComment
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

DELETE

Deletes a user comment.

Restricted to superuser privileges or above. Deletes a single user comment on a film location endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
filmLocationId	path	yes			string (uuid)
userCommentId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/images

GET

Gets all images.

Gets all images, ordered by their time of creation.

Request

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[Image]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new image.

Posts an image. Posting should not be done directly, it should be done on a specific FilmLocation endpoint.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			Image

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Image
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

/images/{imageId}

GET

Gets an image.

Gets a single image on a film location endpoint, referenced by its internal ID

Request

Parameters

Name	Located in	Required	Description	Default	Schema
imageId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Image
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

DELETE

Deletes an image.

Restricted to superuser privileges or above. Deletes a single image on a film location endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
imageId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/productions

GET

Gets all productions/

Gets all of the productions on the productions endpoint, ordered alphabetically by their title.

Request

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[Production]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new production.

Restricted to superuser privileges or above. Posts a new production. Should have an IMDb ID, plot summary, and title at least.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			Production

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Production
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

PATCH

Modifies a production.

Restricted to superuser privileges or above. Patches a production from the productions endpoint. All data will be overwritten - current fields to stay the same must be included as well. The ID should be included in the body.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			Production

Response

Status Code	Reason	Response Model
200	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/productions/{productionId}

GET

Gets a single production.

Gets a single production from the productions endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
productionId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Production
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

DELETE

Deletes a production.

Restricted to superuser privileges or above. Deletes a production from the productions endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
productionId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/productions/{productionId}/poster

GET

Retrieves a poster image for the production.

Retrieves a poster image relayed its source on the OMDb API. Image is returned as a raw StreamingBodyResponse to be deserialized.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
productionId	path	yes			string (uuid)

Response

Content-Type: image/gif, image/jpeg, image/png, video/webm, video/mp4, application/octet-stream

Status Code	Reason	Response Model
200	Operation successful.	StreamingResponseBody
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-
404	Not found. Possible problem in reaching the OMDb API, or no poster for the production may be available.	-

/user_comments

GET

Gets all user comments.

Gets all user comments, ordered by their time of creation.

Request

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[UserComment]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

POST

Posts a new user comment.

Posts a new user comment. Posting should not be done directly, it should be done on a specific FilmLocation endpoint.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			UserComment

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	UserComment
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

/user_comments/{userCommentId}

DELETE

Modifies a user comment.

Restricted to superuser privileges or above. Patches a user comment from the user comments endpoint on a film location. All data will be overwritten - current fields to stay the same must be included as well. The ID of the user comment should be included in the body. Can be used to approve a comment submission.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userCommentId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204	Operation successful.	-
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint requires superuser privileges or higher.	-

/user_comments/{user_comments}

GET

Deletes a user comment.

Restricted to superuser privileges or above. Deletes a single user comment on a film location endpoint, referenced by its internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
user_comments	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	UserComment
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. The user attempting to access this endpoint may be banned from the service.	-

/users

GET

Gets all users.

Admin access only. Gets all users, ordered alphabetically by the name on their account.

Request

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	Operation successful.	Array[GoogleUser]
401	Failure to authorize. Advised to check authorization token header.	-
403	Forbidden to access. This endpoint is restricted to the administrator only.	-

POST

Posts a new user.

Admin access only. Posts a new user to the users endpoint. Should include a Google ID, full name, and gmail address.

Request

Content-Type: application/json

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			GoogleUser

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	successful operation	GoogleUser

PATCH

Modifies a user.

Admin access only. Patches a user from the users endpoint. All data will be overwritten - current fields to stay the same must be included as well. Can be used to ban or unban a user.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
body	body	no			GoogleUser

Response

Status Code	Reason	Response Model
default	successful operation	-

/users/{userId}

GET

Gets a single user.

Admin access only. Gets a user from the users endpoint, referenced by their internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	successful operation	GoogleUser

DELETE

Deletes a user.

Admin access only. Deletes a user from the users endpoint, referenced by their internal ID.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userId	path	yes			string (uuid)

Response

Status Code	Reason	Response Model
204		-

/users/{userId}/film_locations

GET

Gets all locations submitted by a user.

Admin access only. Shows all of the locations submitted by a user in descending order by timestamp. Can be used to monitor activity.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	successful operation	Array[FilmLocation]

/users/{userId}/images

GET

Gets all images submitted by a user.

Admin access only. Shows all of the locations submitted by a user in descending order by timestamp. Can be used to monitor activity.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	successful operation	Array[Image]

/users/{userId}/user_comments

GET

Gets all comments submitted by a user.

Admin access only. Shows all of the comments submitted by a user in descending order by timestamp. Can be used to monitor activity.

Request

Parameters

Name	Located in	Required	Description	Default	Schema
userId	path	yes			string (uuid)

Response

Content-Type: application/json

Status Code	Reason	Response Model
200	successful operation	Array[UserComment]

Definitions

FilmLocation

Name	Type	Mode	Description
id	string (uuid)	read-only	Internal ID for this location.
longCoordinate	number (double)	required	The longitude coordinate of the location.
latCoordinate	number (double)	required	The latitude coordinate of the location.
siteName	string	required	The name of the site.
imdbId	string	optional	The IMDb ID for this location. Included in city data entries.
productionId	string	optional	The transient ID of the production, used to reference during a post.
production	Production	read-only	The production (film or television series) associated with this location.
address	string	optional	The address for this location. Included in city data entries.
shootDate	integer (int64)	optional	The time of the last shoot in epoch date format. Included in city data entries.
originalDetails	string	optional	General information about the last shoot. Included in city data entries
approved	boolean	required	The approval status of the location.
googleId	string	optional	Google ID of the user
userName	string	optional	The full name of the Google user who submitted this content
userPictureUrl	string	optional	The URL of the Google user's profile image.
href	string (uri)	optional	-

GoogleUser

Name	Type	Mode	Description
id	string (uuid)	read-only	Internal ID for this location.
googleId	string	optional	Transient Google ID of the user, used to reference the user during a post.
googleName	string	read-only	The full name on the user's Google Account
gmailAddress	string	read-only	The email address on the Google account.
banned	boolean	optional	The banned status of the user
banReason	string	optional	The reason for a ban.
userRole	string	optional	The user's privilege role in the database, primarily for internal records.
pictureUrl	string	optional	The URL to the user's profile image.
href	string (uri)	optional	-

Image

Name	Type	Mode	Description
id	string (uuid)	read-only	Internal ID for this location.
filmLocation	FilmLocation	optional	-
description	string	optional	An optional description of the image's contents.
url	string	optional	The URL the image is located at.
googleId	string	optional	Google ID of the user
userName	string	optional	The full name of the Google user who submitted this content
userPictureUrl	string	optional	The URL of the Google user's profile image.
approved	boolean	required	The approval status of the location.
href	string (uri)	optional	-

Production

Name	Type	Mode	Description
id	string (uuid)	read-only	Internal ID for this location.
imdbId	string	required	ID of this production associated with its entry in the IMDb.
title	string	required	Title of the production.
type	string	required	Type of "movie" or "series"
releaseYear	string	optional	Release year, can cover a range such as "2008-2010".
plot	string	optional	Plot summary of the production, 300 char max.
href	string (uri)	optional	-

StreamingResponseBody

Name	Type	Mode	Description

UserComment

Name	Type	Mode	Description
id	string (uuid)	read-only	Internal ID for this location.
filmLocation	FilmLocation	read-only	The Film Location associated with this entity.
text	string	optional	The text content of this comment. 4096 character max
googleId	string	optional	Google ID of the user
userName	string	optional	The full name of the Google user who submitted this content
userPictureUrl	string	optional	The URL of the Google user's profile image.
approved	boolean	required	The approval status of the location.
href	string (uri)	optional	-