WASAPhoto/doc/api.yaml

829 lines
25 KiB
YAML

openapi: 3.0.3
info:
title: WASAPhoto API
description: |-
Keep in touch with your friends by sharing photos of special moments, thanks to WASAPhoto! You can
upload your photos directly from your PC, and they will be visible to everyone following you.
version: "2.0.0"
tags:
- name: login
description: Login API
- name: username
description: Operations related to username
- name: followers
description: Operations related to followers
- name: likes
description: Operations related to likes
- name: bans
description: Operations related to bans
- name: profile
description: Operations related to user profiles
- name: photos
description: Operations related to photos
- name: comments
description: Operations related to comments
- name: stream
description: Operations related to the user stream
paths:
/session:
post:
tags: ["login"]
summary: Logs in the user
description: |-
If the user does not exist, it will be created,
and an identifier is returned.
If the user exists, the user identifier is returned.
operationId: doLogin
requestBody:
$ref: "#/components/requestBodies/userDetails"
responses:
'200': #is 201 in the original one
description: User log-in action successful.
content:
application/json:
schema:
$ref: "#/components/schemas/uid_object"
example:
user_id: "123e4567-e89b-12d3-a456-426655440000"
/users/{user_id}/username:
put:
tags: ["username"]
summary: Updates the username
description: Changes the username of the user with the given one.
operationId: setMyUsername
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user to change the username to.
security:
- BearerAuth: []
requestBody:
$ref: "#/components/requestBodies/userDetails"
responses:
'204':
description: Update username action successful.
'409':
description: The chosen username is already taken by another users.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/followers:
get:
tags: ["followers"]
summary: Gets user's followers
description: Get the followers list of the user
operationId: getUserFollowers
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user to follow.
responses:
'200':
description: Returns the user list
content:
application/json:
schema:
type: array
description: The list of followers.
minItems: 0
items:
$ref: "#/components/schemas/uid_name"
example:
- user_id: "123e4567-e89b-12d3-a456-426655440000"
username: "Maria"
- user_id: "123e4567-e89b-12d3-a456-426655440001"
username: "Filippo"
'404':
description: The user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/following:
get:
tags: ["followers"]
summary: Gets following users
description: Get the users that a user is following
operationId: getUserFollowing
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user to follow.
responses:
'200':
description: Returns the user list
content:
application/json:
schema:
type: array
minItems: 0
description: The list of users that the user is following.
items:
$ref: "#/components/schemas/uid_name"
example:
- user_id: "123e4567-e89b-12d3-a456-426655440000"
username: "Maria"
- user_id: "123e4567-e89b-12d3-a456-426655440001"
username: "Filippo"
'404':
description: The user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/followers/{follower_uid}:
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The ID of the user to follow.
- name: follower_uid
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The follower's user ID.
put:
tags: ["followers"]
summary: Follows a user
description: Starts following a user
operationId: followUser
security:
- BearerAuth: []
responses:
'204':
description: Follow user action successful.
'403':
description: The user has no permission perform this action.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
delete:
tags: ["followers"]
summary: Unfollows a user
description: Stops following a user
operationId: unfollowUser
security:
- BearerAuth: []
responses:
'204':
description: Unfollow user action successful.
'404':
description: The user is not followed by follower_uid, or the user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/bans/{ban_uid}:
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the banning user.
- name: ban_uid
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the banned user.
put:
tags: ["bans"]
summary: Bans a user
description: Add a user to the list of banned users of the user.
operationId: banUser
security:
- BearerAuth: []
responses:
'204':
description: Ban user action successful.
'403':
description: The user has no permission to perform this action.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The user does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
delete:
tags: ["bans"]
summary: Unbans a user
description: Removes a ban from the list of banned users of the user.
operationId: unbanUser
security:
- BearerAuth: []
responses:
'204':
description: Unban user action successful.
'403':
description: The user has no permission to perform this action.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The user is not banned by the user.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos/{photo_id}/likes:
get:
tags: ["likes"]
summary: Gets photo likes
description: Get the list of users liking a photo
operationId: getPhotoLikes
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The ID of the author of the photo.
- name: photo_id
in: path
schema:
$ref: "#/components/schemas/photo_id"
required: true
description: The ID of the photo.
responses:
'200':
description: Returns the user list
content:
application/json:
schema:
type: array
minItems: 0
description: An array of users liking the photo.
items:
$ref: "#/components/schemas/uid_name"
example:
- user_id: "123e4567-e89b-12d3-a456-426655440000"
username: "Maria"
- user_id: "123e4567-e89b-12d3-a456-426655440001"
username: "Filippo"
'404':
description: The user or the photo does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos/{photo_id}/likes/{liker_uid}:
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The ID of the author of the photo.
- name: liker_uid
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The ID of the user who likes the photo.
- name: photo_id
in: path
schema:
$ref: "#/components/schemas/photo_id"
required: true
description: The ID of the photo.
put:
tags: ["likes"]
summary: likes a Photo
description: Adds a like to a photo.
operationId: likePhoto
security:
- BearerAuth: []
responses:
'204':
description: Like photo action successful.
'403':
description: The user has no permission to perform this action.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The user or the photo does not exists (or the author of the photo has banned the authorized user).
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
delete:
tags: ["likes"]
summary: Unlikes a photo
description: Removes a like from a photo
operationId: unlikePhoto
security:
- BearerAuth: []
responses:
'204':
description: Unlike photo action successful.
'404':
description: The user or photo does not exists, or the user is not liking the photo.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}:
get:
tags: ["profile"]
summary: Returns user profile
description: Returns the profile of a user, including user's photos, followers, and following users.
operationId: getUserProfile
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
description: The user ID of the user to get the profile of.
required: true
responses:
'200':
description: Returns the profile details of the given user.
content:
application/json:
schema:
$ref: "#/components/schemas/user_profile"
example:
username: "Maria"
followers: 25
following: 32
photos:
- photo_id: 2341
upload_time: "2020-11-20T12:00:00Z"
likes: 2
- photo_id: 2342
upload_time: "2022-10-23T12:01:00Z"
likes: 5
'404':
description: User not found (or the authorized user is banned).
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos:
post:
tags: ["photos"]
summary: Uploads a photo
description: Uploads a photo in the gallery of the authorized user.
operationId: uploadPhoto
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user who uploads the photo.
requestBody:
content:
image/jpeg:
schema:
description: The photo to upload.
type: string
format: binary
responses:
'201':
description: Upload photo action successful.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_success"
example:
status: "Created"
'404':
description: User not found (or the authorized user is banned).
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos/{photo_id}:
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
description: The ID of the author of the photo.
required: true
- name: photo_id
in: path
schema:
$ref: "#/components/schemas/photo_id"
description: The ID of the photo.
required: true
get:
tags: ["photos"]
summary: Downloads a photo
description: Returns the requested photo in binary format.
operationId: getUserPhoto
security:
- BearerAuth: []
responses:
'200':
description: The requested photo in binary format.
content:
image/jpeg:
schema:
#todo it wants lenght
description: The requested photo in binary format.
type: string
format: binary
'404':
description: User or photo not found (or the authorized user is banned by the author of the photo).
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
delete:
tags: ["photos"]
summary: Deletes a photo
description: Deletes a photo in the gallery of the authorized user.
operationId: deletePhoto
security:
- BearerAuth: []
responses:
'204':
description: Delete photo action successful.
'401':
description: The user has no permission to delete that photo.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: User or photo not found.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos/{photo_id}/comments:
parameters:
- name: user_id
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The ID of the author of the photo.
- name: photo_id
in: path
schema:
$ref: "#/components/schemas/photo_id"
required: true
description: The ID of the photo.
get:
tags: ["comments"]
summary: Gets photo comments
description: Gets the list of comments of a photo
operationId: getPhotoComments
security:
- BearerAuth: []
responses:
'200':
description: Returns the comments list
content:
application/json:
schema:
$ref: "#/components/schemas/comments"
example:
- user_id: "a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6"
name: "Maria"
comment: "Nice photo!"
date: "2020-11-20T12:00:00Z"
- user_id: "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
name: "John"
comment: "I like it!"
date: "2021-12-20T13:04:00Z"
'404':
description: The user or the photo does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
post:
tags: ["comments"]
summary: Comments a photo
description: Adds a comment to a photo.
operationId: commentPhoto
security:
- BearerAuth: []
requestBody:
description: The comment to post.
content:
application/json:
schema:
$ref: "#/components/schemas/comment_request"
example:
comment: "Lovely!"
responses:
'204':
description: Comment photo action successful. #todo maybe 201
'404':
description: The user or the photo does not exists (or the author of the photo has banned the authorized user).
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/users/{user_id}/photos/{photo_id}/comments/{comment_id}:
delete:
tags: ["comments"]
summary: Deletes a comment
description: Deletes a photo in the gallery of the authorized user.
operationId: deleteComment
security:
- BearerAuth: []
parameters:
- name: user_id
in: path
description: The ID of the author of the photo.
schema:
$ref: "#/components/schemas/uid"
required: true
- name: photo_id
description: The ID of the photo.
in: path
schema:
$ref: "#/components/schemas/photo_id"
required: true
- name: comment_id
description: The ID of the comment to delete.
in: path
schema:
$ref: "#/components/schemas/comment_id"
required: true
responses:
'204':
description: Delete comment action successful.
'401':
description: The user has no permission to delete that comment.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
'404':
description: The comment does not exists.
content:
application/json:
schema:
$ref: "#/components/schemas/generic_error"
/stream: # todo review path
get:
tags: ["stream"]
summary: Returns user stream
description: Returns the photo stream of the authorized user.
operationId: getMyStream
security:
- BearerAuth: []
parameters:
- name: limit
in: query
schema:
type: integer
default: 25
description: The number of elements to show.
required: false
- name: start_index
in: query
schema:
type: integer
default: 0
description: The starting offset.
required: false
responses:
'200':
description: The photo stream.
content:
application/json:
schema:
$ref: "#/components/schemas/photo_stream"
example:
- user_id: "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
- username: "Federicus"
- photo_id: 1520
- upload_time: "2020-11-20T12:00:00Z"
- likes: 93
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
schemas:
uid_name:
type: object
properties:
user_id:
$ref: "#/components/schemas/uid"
name:
$ref: "#/components/schemas/name"
uid_object:
type: object
description: The user identifier.
properties:
user_id:
$ref: "#/components/schemas/uid"
uid:
type: string
minLength: 36
maxLength: 36
description: The user ID.
format: uuid
example: "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
name_object:
type: object
description: The username of the user.
properties:
name:
$ref: "#/components/schemas/name"
name:
type: string
description: The username of the user.
example: Maria
pattern: '^[a-zA-Z0-9_.]*$'
minLength: 3
maxLength: 16
photo_id:
type: integer
description: The ID of the photo.
example: 1527
comment_id:
type: integer
description: The ID of the comment.
example: 3
upload_time:
type: string
format: date-time
description: Upload time and date.
likes:
type: integer
example: 90
description: Number of likes.
followers_n:
type: integer
example: 420
description: Number of followers.
following_n:
type: integer
example: 69
description: Number of following users.
user_profile:
type: object
description: The profile of the user.
properties:
username:
$ref: "#/components/schemas/name"
followers:
$ref: "#/components/schemas/followers_n"
following:
$ref: "#/components/schemas/following_n"
photos:
$ref: "#/components/schemas/user_photo_stream"
user_photo_stream:
type: array
minItems: 0
description: An array of photos, upload time and likes.
items:
$ref: "#/components/schemas/user_photo_stream_item"
user_photo_stream_item:
type: object
properties:
photo_id:
$ref: "#/components/schemas/photo_id"
upload_time:
$ref: "#/components/schemas/upload_time"
likes:
$ref: "#/components/schemas/likes"
photo_stream:
type: array
minItems: 0
description: An array of photos, author, upload time and likes.
items:
$ref: "#/components/schemas/photo_stream_item"
photo_stream_item:
type: object
properties:
user_id:
$ref: "#/components/schemas/uid"
username:
$ref: "#/components/schemas/name"
photo_id:
$ref: "#/components/schemas/photo_id"
upload_time:
$ref: "#/components/schemas/upload_time"
likes:
$ref: "#/components/schemas/likes"
comments:
type: array
minItems: 0
description: An array of comments.
items:
$ref : "#/components/schemas/comment_item"
comment_item:
type: object
properties:
user_id:
$ref: "#/components/schemas/uid"
name:
$ref: "#/components/schemas/name"
comment:
$ref: "#/components/schemas/comment"
date:
$ref: "#/components/schemas/upload_time"
comment_request:
description: The comment to post.
type: object
properties:
comment:
$ref: "#/components/schemas/comment"
comment:
minLength: 5
maxLength: 100 #todo think about it
pattern: ".*" #everything except newlines
type: string
example: "What a lovely picture! 😊"
description: The comment's text
generic_error:
type: object
description: An object representing an error.
properties:
error:
type: string
description: The error message.
example: "The user does not exist."
generic_success:
type: object
description: An object representing a success.
properties:
status:
type: string
description: The status of the request.
example: "Created"
requestBodies:
userDetails:
description: User details
content:
application/json:
schema:
$ref: "#/components/schemas/name_object"
example:
name: "Maria"
required: true