From 3c7e03f2afe56324e5d2e71366f6d988afca10b8 Mon Sep 17 00:00:00 2001 From: Marco Realacci Date: Tue, 22 Nov 2022 22:11:00 +0100 Subject: [PATCH 1/3] Add GET /users --- doc/api.yaml | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/doc/api.yaml b/doc/api.yaml index 08e5df3..3e1198a 100644 --- a/doc/api.yaml +++ b/doc/api.yaml @@ -73,7 +73,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Username already taken" + status: "Username already taken" '404': description: The user does not exist. content: @@ -435,6 +435,74 @@ paths: $ref: "#/components/schemas/generic_response" example: error: "Resource not found" + /users: + get: + tags: ["search"] + summary: Search users by username + description: Search users whose username contains the given string. + operationId: searchUsers + security: + - BearerAuth: [] + parameters: + - name: query + in: query + schema: + $ref: "#/components/schemas/name" + required: true + description: The username to search. + - name: limit + in: query + schema: + $ref: "#/components/schemas/limit" + description: The number of elements to show. + required: false + - name: start_index + in: query + schema: + $ref: "#/components/schemas/start_index" + description: The starting offset. + required: false + responses: + '200': + description: Returns the user list + content: + application/json: + schema: + type: array + minItems: 0 + maxItems: 100 + description: An array of users whose username contains the given string. + 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: No user found. + content: + application/json: + schema: + $ref: "#/components/schemas/generic_response" + example: + error: "Resource not found" + '400': + description: Some parameters are malformed. + content: + application/json: + schema: + $ref: "#/components/schemas/generic_response" + example: + error: "Invalid start_index or limit value" + '401': + description: The user is not logged in. + content: + application/json: + schema: + $ref: "#/components/schemas/generic_response" + example: + error: "Unauthorized" /users/{user_id}: get: From f896e9ab48c626f678f9d2746c29945202501307 Mon Sep 17 00:00:00 2001 From: Marco Realacci Date: Tue, 22 Nov 2022 22:11:24 +0100 Subject: [PATCH 2/3] Fix: replaced error with status in responses --- doc/api.yaml | 60 ++++++++++++++++++++++++++-------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/doc/api.yaml b/doc/api.yaml index 3e1198a..2ae4ca2 100644 --- a/doc/api.yaml +++ b/doc/api.yaml @@ -81,7 +81,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" /users/{user_id}/followers: get: @@ -121,7 +121,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" /users/{user_id}/following: get: tags: ["followers"] @@ -161,7 +161,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" /users/{user_id}/followers/{follower_uid}: parameters: @@ -200,7 +200,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Forbidden" + status: "Forbidden" '404': description: The resource does not exist. content: @@ -208,7 +208,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" '400': description: Trying to follow a user that does not exist. content: @@ -216,7 +216,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" delete: tags: ["followers"] summary: Unfollows a user @@ -234,7 +234,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" /users/{user_id}/bans/{ban_uid}: parameters: @@ -267,7 +267,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Forbidden" + status: "Forbidden" '404': description: The user does not exist. content: @@ -275,7 +275,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" delete: tags: ["bans"] @@ -294,7 +294,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Forbidden" + status: "Forbidden" '404': description: The user is not banned by the user. content: @@ -302,7 +302,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "User not found" + status: "User not found" /users/{user_id}/photos/{photo_id}/likes: get: @@ -361,7 +361,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users/{user_id}/photos/{photo_id}/likes/{liker_uid}: parameters: @@ -400,7 +400,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Forbidden" + status: "Forbidden" '404': description: Resource not found (or the author of the photo has banned the authorized user). content: @@ -408,7 +408,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" '400': description: Bad URI (maybe liker_uid is invalid). content: @@ -416,7 +416,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Bad photo_id" + status: "Bad photo_id" delete: tags: ["likes"] summary: Unlikes a photo @@ -434,7 +434,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users: get: tags: ["search"] @@ -486,7 +486,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" '400': description: Some parameters are malformed. content: @@ -494,7 +494,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Invalid start_index or limit value" + status: "Invalid start_index or limit value" '401': description: The user is not logged in. content: @@ -502,7 +502,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Unauthorized" + status: "Unauthorized" /users/{user_id}: get: @@ -539,7 +539,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users/{user_id}/photos: parameters: @@ -584,7 +584,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" '400': description: Bad request, there is an error in one of the parameters. content: @@ -592,7 +592,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Invalid limit or start_index" + status: "Invalid limit or start_index" post: tags: ["photos"] @@ -624,7 +624,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users/{user_id}/photos/{photo_id}: parameters: @@ -664,7 +664,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" delete: tags: ["photos"] summary: Deletes a photo @@ -682,7 +682,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Unauthorized" + status: "Unauthorized" '404': description: User or photo not found. content: @@ -690,7 +690,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users/{user_id}/photos/{photo_id}/comments: parameters: @@ -751,7 +751,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" post: tags: ["comments"] summary: Comments a photo @@ -777,7 +777,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /users/{user_id}/photos/{photo_id}/comments/{comment_id}: delete: @@ -816,7 +816,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Unauthorized" + status: "Unauthorized" '404': description: The comment does not exists. content: @@ -824,7 +824,7 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - error: "Resource not found" + status: "Resource not found" /stream: # todo review path get: From 2baddf724d6ead3bd46d73609fc03d6c307c30b2 Mon Sep 17 00:00:00 2001 From: Marco Realacci Date: Tue, 22 Nov 2022 22:13:46 +0100 Subject: [PATCH 3/3] Clarified 400 responses descriptions --- doc/api.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api.yaml b/doc/api.yaml index 2ae4ca2..f0b723b 100644 --- a/doc/api.yaml +++ b/doc/api.yaml @@ -208,8 +208,8 @@ paths: schema: $ref: "#/components/schemas/generic_response" example: - status: "User not found" - '400': + status: "Resource not found" + '400': # todo: not sure if this is the right error code description: Trying to follow a user that does not exist. content: application/json: @@ -586,13 +586,13 @@ paths: example: status: "Resource not found" '400': - description: Bad request, there is an error in one of the parameters. + description: Some parameters are malformed. content: application/json: schema: $ref: "#/components/schemas/generic_response" example: - status: "Invalid limit or start_index" + status: "Invalid start_index or limit value" post: tags: ["photos"]