WASAPhoto/api/api.yaml

522 lines
15 KiB
YAML
Raw Normal View History

2022-11-04 12:41:07 +01:00
openapi: 3.0.3
info:
title: WASAPhoto API
2022-11-04 12:41:07 +01:00
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.
2022-11-15 23:23:33 +01:00
version: "2.0.0"
2022-11-04 12:41:07 +01:00
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:
'201':
2022-11-15 23:23:33 +01:00
description: User log-in action successful.
2022-11-04 12:41:07 +01:00
content:
application/json:
schema:
type: object
properties:
2022-11-15 23:23:33 +01:00
user_id: #todo parameter name
$ref: "#/components/schemas/uid"
2022-11-04 12:41:07 +01:00
2022-11-15 23:23:33 +01:00
/users/{user_id}/username:
2022-11-08 14:53:34 +01:00
put:
2022-11-15 23:23:33 +01:00
tags: ["username"]
2022-11-08 14:53:34 +01:00
summary: Updates the username
2022-11-15 23:23:33 +01:00
description: Changes the username of the user with the given one.
2022-11-04 12:41:07 +01:00
operationId: setMyUsername
2022-11-15 23:31:33 +01:00
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.
2022-11-04 12:41:07 +01:00
security:
- BearerAuth: []
requestBody:
$ref: "#/components/requestBodies/userDetails"
2022-11-04 12:41:07 +01:00
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Update username action successful.
2022-11-08 14:53:34 +01:00
'409':
2022-11-15 23:23:33 +01:00
description: The chosen username is already taken by another user.
2022-11-04 12:41:07 +01:00
2022-11-15 23:23:33 +01:00
/users/{user_id}/followers/{follower_uid}:
put:
2022-11-08 14:53:34 +01:00
tags: ["followers"]
summary: Follows a user
2022-11-04 12:41:07 +01:00
description: Starts following a user
operationId: followUser
security:
- BearerAuth: []
2022-11-08 14:53:34 +01:00
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user to follow.
- name: follower_uid
in: path
schema:
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The new follower's user ID.
2022-11-04 12:41:07 +01:00
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Follow user action successful.
'403':
description: The user has no permission perform this action.
2022-11-08 14:53:34 +01:00
delete:
tags: ["followers"]
summary: Unfollows a user
2022-11-04 12:41:07 +01:00
description: Stops following a user
operationId: unfollowUser
security:
- BearerAuth: []
2022-11-08 14:53:34 +01:00
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The user ID of the user to remove a follower from.
- name: follower_uid
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the follower to remove.
2022-11-04 12:41:07 +01:00
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Unfollow user action successful.
'404':
description: The user is not followed by the user.
2022-11-08 14:53:34 +01:00
2022-11-15 23:23:33 +01:00
/users/{user_id}/bans/{ban_uid}:
put:
2022-11-08 14:53:34 +01:00
tags: ["bans"]
summary: Bans a user
2022-11-15 23:23:33 +01:00
description: Add a user to the list of banned users of the user.
2022-11-04 12:41:07 +01:00
operationId: banUser
security:
- BearerAuth: []
2022-11-15 23:23:33 +01:00
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 user to ban.
2022-11-04 12:41:07 +01:00
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Ban user action successful.
'403':
description: The user has no permission to perform this action.
2022-11-08 14:53:34 +01:00
delete:
tags: ["bans"]
summary: Unbans a user
2022-11-15 23:23:33 +01:00
description: Removes a ban from the list of banned users of the user.
2022-11-04 12:41:07 +01:00
operationId: unbanUser
security:
- BearerAuth: []
2022-11-08 14:53:34 +01:00
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The user ID of the unbanning user.
- name: ban_uid
in: path
schema:
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the user to unban.
2022-11-04 12:41:07 +01:00
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Unban user action successful.
'403':
description: The user has no permission to perform this action.
'404':
description: The user is not banned by the user.
2022-11-04 12:41:07 +01:00
2022-11-15 23:23:33 +01:00
/users/{user_id}/photos/{photo_id}/likes/{liker_uid}:
put:
tags: ["likes"]
summary: likes a Photo
description: Adds a like to a photo.
operationId: likePhoto
security:
- BearerAuth: []
2022-11-08 14:53:34 +01:00
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
required: true
description: The user ID of the owner of the photo to add a like to.
- name: liker_uid
in: path
schema:
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The user ID of the user who likes the photo.
- name: photo_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_id"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The ID of the photo to like.
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Like photo action successful.
'403':
description: The user has no permission to perform this action.
'404':
2022-11-15 23:23:33 +01:00
description: The photo does not exists, or the author of the photo has banned the user.
2022-11-08 14:53:34 +01:00
delete:
2022-11-15 23:23:33 +01:00
tags: ["likes"]
summary: Unlikes a photo
description: Removes a like from a photo
operationId: unlikePhoto
security:
- BearerAuth: []
2022-11-08 14:53:34 +01:00
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The user ID of the owner of the photo to remove a like from.
- name: liker_uid
2022-11-08 14:53:34 +01:00
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
2022-11-08 14:53:34 +01:00
required: true
2022-11-15 23:23:33 +01:00
description: The user ID of the user that was liking the photo.
- name: photo_id
in: path
schema:
$ref: "#/components/schemas/photo_id"
required: true
description: The ID of the photo to remove a like from.
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Unlike photo action successful.
'404':
2022-11-15 23:23:33 +01:00
description: The photo does not exists or the user was not liking the photo.
2022-11-15 23:23:33 +01:00
/users/{user_id}:
get:
2022-11-08 14:53:34 +01:00
tags: ["profile"]
summary: Returns user profile
2022-11-15 23:23:33 +01:00
description: Returns the profile of a user, including user's photos, followers, and following users.
operationId: getUserProfile
2022-11-15 23:23:33 +01:00
security:
- BearerAuth: []
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
description: The user ID of the user to get the profile of.
required: true
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Returns the profile details of the given user.
content:
application/json:
schema:
type: object
properties:
2022-11-15 23:23:33 +01:00
username:
$ref: "#/components/schemas/name"
followers:
2022-11-08 14:53:34 +01:00
type: array
2022-11-15 23:23:33 +01:00
description: Array of users that the user is following.
2022-11-08 14:53:34 +01:00
items:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid_name"
2022-11-08 14:53:34 +01:00
following:
type: array
2022-11-15 23:23:33 +01:00
description: Array of users that are following the user.
2022-11-08 14:53:34 +01:00
items:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid_name"
photos:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/user_photo_stream"
'404':
2022-11-15 23:23:33 +01:00
description: User not found (or the authorized user is banned).
/users/{user_id}/photos:
post:
2022-11-08 14:53:34 +01:00
tags: ["photos"]
summary: Uploads a photo
2022-11-15 23:23:33 +01:00
description: Uploads a photo in the gallery of the authorized user.
operationId: uploadPhoto
security:
- BearerAuth: []
2022-11-15 23:23:33 +01:00
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:
format: binary
responses:
'201':
2022-11-15 23:23:33 +01:00
description: Upload photo action successful.
2022-11-15 23:23:33 +01:00
/users/{user_id}/photos/{photo_id}:
get:
2022-11-08 14:53:34 +01:00
tags: ["photos"]
2022-11-15 23:23:33 +01:00
summary: Downloads a photo
description: Returns the requested photo in binary format.
operationId: getUserPhoto
2022-11-15 23:23:33 +01:00
security:
- BearerAuth: []
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
description: The user ID of the user who owns the photo.
required: true
2022-11-15 23:23:33 +01:00
- name: photo_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_id"
description: The ID of the photo to download.
required: true
responses:
'200':
2022-11-15 23:23:33 +01:00
description: The requested photo in binary format.
content:
image/jpeg:
schema:
format: binary
'404':
2022-11-15 23:23:33 +01:00
description: Photo not found (or the user is banned by the owner of the photo).
delete:
2022-11-08 14:53:34 +01:00
tags: ["photos"]
summary: Deletes a photo
2022-11-15 23:23:33 +01:00
description: Deletes a photo in the gallery of the authorized user.
operationId: deletePhoto
security:
- BearerAuth: []
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
description: The user ID of the user who deletes the photo.
required: true
2022-11-15 23:23:33 +01:00
- name: photo_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_id"
description: The ID of the photo to delete.
required: true
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Delete photo action successful.
'401':
2022-11-15 23:23:33 +01:00
description: The user has no permission to delete that photo.
2022-11-15 23:23:33 +01:00
/users/{user_id}/photos/{photo_id}/comments:
post:
tags: ["comments"]
2022-11-15 23:23:33 +01:00
summary: Comments a photo
description: Adds a comment to a photo.
operationId: commentPhoto
security:
- BearerAuth: []
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
required: true
2022-11-15 23:23:33 +01:00
- name: photo_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_id"
required: true
requestBody:
2022-11-15 23:23:33 +01:00
description: The comment to post.
content:
application/json:
schema:
type: object
properties:
comment:
type: string
example: "What a lovely picture! 😊"
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Comment photo action successful.
'404':
2022-11-15 23:23:33 +01:00
description: The photo does not exists (or the author of the photo has banned the user).
2022-11-15 23:23:33 +01:00
/users/{user_id}/photos/{photo_id}/comments/{comment_id}:
delete:
tags: ["comments"]
summary: Deletes a comment
2022-11-15 23:23:33 +01:00
description: Deletes a photo in the gallery of the authorized user.
operationId: deleteComment
security:
- BearerAuth: []
parameters:
2022-11-15 23:23:33 +01:00
- name: user_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/uid"
required: true
2022-11-15 23:23:33 +01:00
- name: photo_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_id"
required: true
2022-11-15 23:23:33 +01:00
- name: comment_id
in: path
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/comment_id"
required: true
responses:
'200':
2022-11-15 23:23:33 +01:00
description: Delete comment action successful.
'401':
description: The user has no permission to delete that comment.
'404':
description: The comment does not exists.
/stream: #todo path
get:
tags: ["stream"]
summary: Returns user stream
2022-11-15 23:23:33 +01:00
description: Returns the photo stream of the authorized user.
operationId: getMyStream
security:
2022-11-15 23:23:33 +01:00
- BearerAuth: []
parameters:
- name: limit
in: query
schema:
type: integer
default: 25
2022-11-15 23:23:33 +01:00
description: The number of elements to show.
required: false
- name: startIndex
in: query
schema:
type: integer
default: 0
2022-11-15 23:23:33 +01:00
description: The starting offset.
required: false
responses:
'200':
2022-11-15 23:23:33 +01:00
description: The photo stream.
content:
application/json:
schema:
2022-11-15 23:23:33 +01:00
$ref: "#/components/schemas/photo_stream"
2022-11-04 12:41:07 +01:00
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
schemas:
2022-11-15 23:23:33 +01:00
uid_name:
type: object
properties:
user_id:
$ref: "#/components/schemas/uid"
name:
$ref: "#/components/schemas/name"
uid:
type: string
format: uuid
example: "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
name:
type: string
example: Maria
pattern: 'ˆ.*?$'
minLength: 3
maxLength: 16
2022-11-15 23:23:33 +01:00
photo_id:
type: integer
2022-11-15 23:23:33 +01:00
description: The ID of the photo.
example: 1527
2022-11-15 23:23:33 +01:00
comment_id:
type: integer
2022-11-15 23:23:33 +01:00
description: The ID of the comment.
example: 3
2022-11-15 23:23:33 +01:00
upload_time:
type: string
format: date-time
2022-11-15 23:23:33 +01:00
description: Photo upload time and date.
likes:
type: integer
example: 90
2022-11-15 23:23:33 +01:00
description: Number of likes.
user_photo_stream:
type: array
items:
type: object
properties:
2022-11-15 23:23:33 +01:00
photo_id:
$ref: "#/components/schemas/photo_id"
upload_time:
$ref: "#/components/schemas/upload_time"
likes:
$ref: "#/components/schemas/likes"
2022-11-15 23:23:33 +01:00
photo_stream:
type: array
items:
type: object
properties:
2022-11-15 23:23:33 +01:00
user_id:
$ref: "#/components/schemas/uid"
username:
$ref: "#/components/schemas/name"
2022-11-15 23:23:33 +01:00
photo_id:
$ref: "#/components/schemas/photo_id"
upload_time:
$ref: "#/components/schemas/upload_time"
likes:
$ref: "#/components/schemas/likes"
2022-11-04 12:41:07 +01:00
requestBodies:
userDetails:
description: User details
content:
application/json:
schema:
type: object
properties:
name:
$ref: "#/components/schemas/name"
2022-11-04 12:41:07 +01:00
required: true