From dcf2526aad541a169f90e7cf990e6b33844ece48 Mon Sep 17 00:00:00 2001 From: Alejandro Celaya Date: Tue, 9 Feb 2021 22:03:03 +0100 Subject: [PATCH] Documented swagger for new orphan visits endpoint --- docs/swagger/definitions/OrphanVisit.json | 23 ++++ docs/swagger/definitions/Visit.json | 1 + docs/swagger/paths/v2_visits_orphan.json | 141 ++++++++++++++++++++++ docs/swagger/swagger.json | 3 + 4 files changed, 168 insertions(+) create mode 100644 docs/swagger/definitions/OrphanVisit.json create mode 100644 docs/swagger/paths/v2_visits_orphan.json diff --git a/docs/swagger/definitions/OrphanVisit.json b/docs/swagger/definitions/OrphanVisit.json new file mode 100644 index 00000000..04d8386d --- /dev/null +++ b/docs/swagger/definitions/OrphanVisit.json @@ -0,0 +1,23 @@ +{ + "type": "object", + "required": ["visitedUrl", "type"], + "allOf": [{ + "$ref": "./Visit.json" + }], + "properties": { + "visitedUrl": { + "type": "string", + "nullable": true, + "description": "The originally visited URL that triggered the tracking of this visit" + }, + "type": { + "type": "string", + "enum": [ + "invalid_short_url", + "base_url", + "regular_404" + ], + "description": "Tells the type of orphan visit" + } + } +} diff --git a/docs/swagger/definitions/Visit.json b/docs/swagger/definitions/Visit.json index 9e1eb5b5..e004e4fe 100644 --- a/docs/swagger/definitions/Visit.json +++ b/docs/swagger/definitions/Visit.json @@ -1,5 +1,6 @@ { "type": "object", + "required": ["referer", "date", "userAgent", "visitLocation"], "properties": { "referer": { "type": "string", diff --git a/docs/swagger/paths/v2_visits_orphan.json b/docs/swagger/paths/v2_visits_orphan.json new file mode 100644 index 00000000..683f40ec --- /dev/null +++ b/docs/swagger/paths/v2_visits_orphan.json @@ -0,0 +1,141 @@ +{ + "get": { + "operationId": "getOrphanVisits", + "tags": [ + "Visits" + ], + "summary": "List orphan visits", + "description": "Get the list of visits to invalid short URLs, the base URL or any other 404.", + "parameters": [ + { + "$ref": "../parameters/version.json" + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + } + ], + "security": [ + { + "ApiKey": [] + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "../definitions/OrphanVisit.json" + } + }, + "pagination": { + "$ref": "../definitions/Pagination.json" + } + } + } + } + } + } + }, + "examples": { + "application/json": { + "visits": { + "data": [ + { + "referer": "https://twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0 Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0", + "visitLocation": null, + "visitedUrl": "https://doma.in", + "type": "base_url" + }, + { + "referer": "https://t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America/Los_Angeles" + }, + "visitedUrl": "https://doma.in/foo", + "type": "invalid_short_url" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler/1.4", + "visitLocation": null, + "visitedUrl": "https://doma.in/foo/bar/baz", + "type": "regular_404" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + }, + "500": { + "description": "Unexpected error.", + "content": { + "application/problem+json": { + "schema": { + "$ref": "../definitions/Error.json" + } + } + } + } + } + } +} diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json index dc834905..21547f90 100644 --- a/docs/swagger/swagger.json +++ b/docs/swagger/swagger.json @@ -95,6 +95,9 @@ "/rest/v{version}/tags/{tag}/visits": { "$ref": "paths/v2_tags_{tag}_visits.json" }, + "/rest/v{version}/visits/orphan": { + "$ref": "paths/v2_visits_orphan.json" + }, "/rest/v{version}/domains": { "$ref": "paths/v2_domains.json"