From 3cf253fd0f5264e4532de27f65e79ce47b37880f Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Sun, 14 May 2023 18:25:21 +0200 Subject: [PATCH] Document short URLs visits deletion endpoint --- docs/swagger/parameters/shortCode.json | 9 ++ .../paths/v1_short-urls_{shortCode}.json | 24 +----- .../v1_short-urls_{shortCode}_visits.json | 82 +++++++++++++++++-- docs/swagger/paths/{shortCode}.json | 8 +- docs/swagger/paths/{shortCode}_qr-code.json | 8 +- docs/swagger/paths/{shortCode}_track.json | 8 +- 6 files changed, 90 insertions(+), 49 deletions(-) create mode 100644 docs/swagger/parameters/shortCode.json diff --git a/docs/swagger/parameters/shortCode.json b/docs/swagger/parameters/shortCode.json new file mode 100644 index 00000000..f8eddca2 --- /dev/null +++ b/docs/swagger/parameters/shortCode.json @@ -0,0 +1,9 @@ +{ + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } +} diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}.json b/docs/swagger/paths/v1_short-urls_{shortCode}.json index e639f362..408d166c 100644 --- a/docs/swagger/paths/v1_short-urls_{shortCode}.json +++ b/docs/swagger/paths/v1_short-urls_{shortCode}.json @@ -11,13 +11,7 @@ "$ref": "../parameters/version.json" }, { - "name": "shortCode", - "in": "path", - "description": "The short code to resolve.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" }, { "$ref": "../parameters/domain.json" @@ -127,13 +121,7 @@ "$ref": "../parameters/version.json" }, { - "name": "shortCode", - "in": "path", - "description": "The short code to edit.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" }, { "$ref": "../parameters/domain.json" @@ -295,13 +283,7 @@ "$ref": "../parameters/version.json" }, { - "name": "shortCode", - "in": "path", - "description": "The short code to edit.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" }, { "$ref": "../parameters/domain.json" diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json index e86bb698..2f102711 100644 --- a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json +++ b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json @@ -11,13 +11,7 @@ "$ref": "../parameters/version.json" }, { - "name": "shortCode", - "in": "path", - "description": "The short code for the short URL from which we want to get the visits.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" }, { "$ref": "../parameters/domain.json" @@ -172,5 +166,79 @@ } } } + }, + + "delete": { + "operationId": "deleteShortUrlVisits", + "tags": [ + "Visits" + ], + "summary": "Delete visits for short URL", + "description": "Delete all existing visits on the short URL behind provided short code.", + "parameters": [ + { + "$ref": "../parameters/version.json" + }, + { + "$ref": "../parameters/shortCode.json" + }, + { + "$ref": "../parameters/domain.json" + } + ], + "security": [ + { + "ApiKey": [] + } + ], + "responses": { + "200": { + "description": "Deleted visits", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "deletedVisits": { + "description": "Amount of affected visits", + "type": "number" + } + } + }, + "example": { + "deletedVisits": 536 + } + } + } + }, + "404": { + "description": "The short code does not belong to any short URL.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "../definitions/Error.json" + }, + "examples": { + "Short URL not found with API v3 and newer": { + "$ref": "../examples/short-url-not-found-v3.json" + }, + "Short URL not found previous to API v3": { + "$ref": "../examples/short-url-not-found-v2.json" + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "../definitions/Error.json" + } + } + } + } + } } } diff --git a/docs/swagger/paths/{shortCode}.json b/docs/swagger/paths/{shortCode}.json index bbebacbd..464063da 100644 --- a/docs/swagger/paths/{shortCode}.json +++ b/docs/swagger/paths/{shortCode}.json @@ -8,13 +8,7 @@ "description": "Represents a short URL. Tracks the visit and redirects tio the corresponding long URL", "parameters": [ { - "name": "shortCode", - "in": "path", - "description": "The short code to resolve.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" } ], "responses": { diff --git a/docs/swagger/paths/{shortCode}_qr-code.json b/docs/swagger/paths/{shortCode}_qr-code.json index dd5c8b8a..ca66a079 100644 --- a/docs/swagger/paths/{shortCode}_qr-code.json +++ b/docs/swagger/paths/{shortCode}_qr-code.json @@ -8,13 +8,7 @@ "description": "Generates a QR code image pointing to a short URL.
Since this is not an API endpoint but an image one, when an invalid value is provided for any of the query params, they will fall to their default values instead of throwing an error.", "parameters": [ { - "name": "shortCode", - "in": "path", - "description": "The short code to resolve.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" }, { "name": "size", diff --git a/docs/swagger/paths/{shortCode}_track.json b/docs/swagger/paths/{shortCode}_track.json index 50f6bc5e..96e32411 100644 --- a/docs/swagger/paths/{shortCode}_track.json +++ b/docs/swagger/paths/{shortCode}_track.json @@ -8,13 +8,7 @@ "description": "Generates a 1px transparent image which can be used to track emails with a short URL", "parameters": [ { - "name": "shortCode", - "in": "path", - "description": "The short code to resolve.", - "required": true, - "schema": { - "type": "string" - } + "$ref": "../parameters/shortCode.json" } ], "responses": {