From 60d3c09da53d409a800e5cabdced80ab83c43876 Mon Sep 17 00:00:00 2001
From: Alejandro Celaya <alejandro@alejandrocelaya.com>
Date: Thu, 28 Nov 2019 19:37:22 +0100
Subject: [PATCH] Updated API docs to reference the use of
application/problem+json
---
docs/swagger/definitions/Error.json | 23 +++++++++-
.../definitions/InvalidShortUrlMeta.json | 6 +++
docs/swagger/paths/v1_short-urls.json | 31 +++++++++++---
docs/swagger/paths/v1_short-urls_shorten.json | 15 ++++---
.../paths/v1_short-urls_{shortCode}.json | 42 ++++++++-----------
.../paths/v1_short-urls_{shortCode}_tags.json | 2 +-
.../v1_short-urls_{shortCode}_visits.json | 4 +-
docs/swagger/paths/v1_tags.json | 12 +++---
docs/swagger/paths/{shortCode}.json | 10 -----
docs/swagger/paths/{shortCode}_preview.json | 10 -----
docs/swagger/paths/{shortCode}_qr-code.json | 10 -----
docs/swagger/paths/{shortCode}_track.json | 10 -----
docs/swagger/swagger.json | 12 +++---
13 files changed, 94 insertions(+), 93 deletions(-)
create mode 100644 docs/swagger/definitions/InvalidShortUrlMeta.json
diff --git a/docs/swagger/definitions/Error.json b/docs/swagger/definitions/Error.json
index 3585227d..006fa47a 100644
--- a/docs/swagger/definitions/Error.json
+++ b/docs/swagger/definitions/Error.json
@@ -1,13 +1,32 @@
{
"type": "object",
+ "required": ["type", "title", "detail", "status"],
"properties": {
- "code": {
+ "type": {
"type": "string",
"description": "A machine unique code"
},
+ "title": {
+ "type": "string",
+ "description": "A unique title"
+ },
+ "detail": {
+ "type": "string",
+ "description": "A human-friendly error description"
+ },
+ "status": {
+ "type": "number",
+ "description": "HTTP response status code"
+ },
+ "code": {
+ "type": "string",
+ "description": "**[Deprecated] Use type instead. Not returned for v2 of the REST API** A machine unique code",
+ "deprecated": true
+ },
"message": {
"type": "string",
- "description": "A human-friendly error message"
+ "description": "**[Deprecated] Use detail instead. Not returned for v2 of the REST API** A human-friendly error message",
+ "deprecated": true
}
}
}
diff --git a/docs/swagger/definitions/InvalidShortUrlMeta.json b/docs/swagger/definitions/InvalidShortUrlMeta.json
new file mode 100644
index 00000000..ebe1fa34
--- /dev/null
+++ b/docs/swagger/definitions/InvalidShortUrlMeta.json
@@ -0,0 +1,6 @@
+{
+ "type": "object",
+ "properties": {
+
+ }
+}
diff --git a/docs/swagger/paths/v1_short-urls.json b/docs/swagger/paths/v1_short-urls.json
index f8fa1ec8..07ed36cc 100644
--- a/docs/swagger/paths/v1_short-urls.json
+++ b/docs/swagger/paths/v1_short-urls.json
@@ -150,7 +150,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -256,11 +256,32 @@
}
},
"400": {
- "description": "The long URL was not provided or is invalid.",
+ "description": "Some of provided data is invalid. Check extra fields to know exactly what.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
- "$ref": "../definitions/Error.json"
+ "type": "object",
+ "allOf": [
+ {
+ "$ref": "./Error.json"
+ },
+ {
+ "type": "object",
+ "properties": {
+ "invalidElements": {
+ "$ref": "./InvalidShortUrlMeta.json"
+ },
+ "url": {
+ "type": "string",
+ "description": "A URL that could not be verified, if the error type is INVALID_URL"
+ },
+ "customSlug": {
+ "type": "string",
+ "description": "Provided custom slug when the error type is INVALID_SLUG"
+ }
+ }
+ }
+ ]
}
}
}
@@ -268,7 +289,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
diff --git a/docs/swagger/paths/v1_short-urls_shorten.json b/docs/swagger/paths/v1_short-urls_shorten.json
index d0c3c4c7..d1887ddd 100644
--- a/docs/swagger/paths/v1_short-urls_shorten.json
+++ b/docs/swagger/paths/v1_short-urls_shorten.json
@@ -77,7 +77,7 @@
"400": {
"description": "The long URL was not provided or is invalid.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -89,9 +89,12 @@
}
},
"examples": {
- "application/json": {
- "error": "INVALID_URL",
- "message": "Provided URL foo is invalid. Try with a different one."
+ "application/problem+json": {
+ "title": "Invalid URL",
+ "type": "INVALID_URL",
+ "detail": "Provided URL foo is invalid. Try with a different one.",
+ "status": 400,
+ "url": "https://invalid-url.com"
},
"text/plain": "INVALID_URL"
}
@@ -99,7 +102,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -111,7 +114,7 @@
}
},
"examples": {
- "application/json": {
+ "application/problem+json": {
"error": "INTERNAL_SERVER_ERROR",
"message": "Unexpected error occurred"
},
diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}.json b/docs/swagger/paths/v1_short-urls_{shortCode}.json
index bbb7145c..0a5cbed7 100644
--- a/docs/swagger/paths/v1_short-urls_{shortCode}.json
+++ b/docs/swagger/paths/v1_short-urls_{shortCode}.json
@@ -62,20 +62,10 @@
}
}
},
- "400": {
- "description": "Provided shortCode does not match the character set currently used by the app to generate short codes.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "../definitions/Error.json"
- }
- }
- }
- },
"404": {
"description": "No URL was found for provided short code.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -85,7 +75,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -153,7 +143,7 @@
"400": {
"description": "Provided meta arguments are invalid.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -163,7 +153,7 @@
"404": {
"description": "No short URL was found for provided short code.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -173,7 +163,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -242,7 +232,7 @@
"400": {
"description": "Provided meta arguments are invalid.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -252,7 +242,7 @@
"404": {
"description": "No short URL was found for provided short code.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -262,7 +252,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -302,26 +292,28 @@
"204": {
"description": "The short URL has been properly deleted."
},
- "400": {
+ "422": {
"description": "The visits threshold in shlink does not allow this short URL to be deleted.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
}
},
"examples": {
- "application/json": {
- "error": "INVALID_SHORTCODE_DELETION",
- "message": "It is not possible to delete URL with short code \"abc123\" because it has reached more than \"15\" visits."
+ "application/problem+json": {
+ "title": "Cannot delete short URL",
+ "type": "INVALID_SHORTCODE_DELETION",
+ "detail": "It is not possible to delete URL with short code \"abc123\" because it has reached more than \"15\" visits.",
+ "status": 422
}
}
},
"404": {
"description": "No short URL was found for provided short code.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -331,7 +323,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}_tags.json b/docs/swagger/paths/v1_short-urls_{shortCode}_tags.json
index ab05d230..de3d0c9b 100644
--- a/docs/swagger/paths/v1_short-urls_{shortCode}_tags.json
+++ b/docs/swagger/paths/v1_short-urls_{shortCode}_tags.json
@@ -78,7 +78,7 @@
"400": {
"description": "The request body does not contain a \"tags\" param with array type.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
diff --git a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json
index a3cf5f10..d5dd243c 100644
--- a/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json
+++ b/docs/swagger/paths/v1_short-urls_{shortCode}_visits.json
@@ -132,7 +132,7 @@
"404": {
"description": "The short code does not belong to any short URL.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -142,7 +142,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
diff --git a/docs/swagger/paths/v1_tags.json b/docs/swagger/paths/v1_tags.json
index 5bf260bb..faa83ed9 100644
--- a/docs/swagger/paths/v1_tags.json
+++ b/docs/swagger/paths/v1_tags.json
@@ -53,7 +53,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -140,7 +140,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -197,7 +197,7 @@
"400": {
"description": "You have not provided either the oldName or the newName params.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -207,7 +207,7 @@
"404": {
"description": "There's no tag found with the name provided in oldName param.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -217,7 +217,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
@@ -263,7 +263,7 @@
"500": {
"description": "Unexpected error.",
"content": {
- "application/json": {
+ "application/problem+json": {
"schema": {
"$ref": "../definitions/Error.json"
}
diff --git a/docs/swagger/paths/{shortCode}.json b/docs/swagger/paths/{shortCode}.json
index eccd5ba1..bbebacbd 100644
--- a/docs/swagger/paths/{shortCode}.json
+++ b/docs/swagger/paths/{shortCode}.json
@@ -20,16 +20,6 @@
"responses": {
"302": {
"description": "Visit properly tracked and redirected"
- },
- "500": {
- "description": "Unexpected error.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "../definitions/Error.json"
- }
- }
- }
}
}
}
diff --git a/docs/swagger/paths/{shortCode}_preview.json b/docs/swagger/paths/{shortCode}_preview.json
index f6168b4d..98df559c 100644
--- a/docs/swagger/paths/{shortCode}_preview.json
+++ b/docs/swagger/paths/{shortCode}_preview.json
@@ -29,16 +29,6 @@
}
}
}
- },
- "500": {
- "description": "Unexpected error.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "../definitions/Error.json"
- }
- }
- }
}
}
}
diff --git a/docs/swagger/paths/{shortCode}_qr-code.json b/docs/swagger/paths/{shortCode}_qr-code.json
index 14a8fddc..300a7429 100644
--- a/docs/swagger/paths/{shortCode}_qr-code.json
+++ b/docs/swagger/paths/{shortCode}_qr-code.json
@@ -40,16 +40,6 @@
}
}
}
- },
- "500": {
- "description": "Unexpected error.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "../definitions/Error.json"
- }
- }
- }
}
}
}
diff --git a/docs/swagger/paths/{shortCode}_track.json b/docs/swagger/paths/{shortCode}_track.json
index b4b62bba..50f6bc5e 100644
--- a/docs/swagger/paths/{shortCode}_track.json
+++ b/docs/swagger/paths/{shortCode}_track.json
@@ -28,16 +28,6 @@
}
}
}
- },
- "500": {
- "description": "Unexpected error.",
- "content": {
- "application/json": {
- "schema": {
- "$ref": "../definitions/Error.json"
- }
- }
- }
}
}
}
diff --git a/docs/swagger/swagger.json b/docs/swagger/swagger.json
index 6dd3ff8f..2d0cb1c1 100644
--- a/docs/swagger/swagger.json
+++ b/docs/swagger/swagger.json
@@ -71,24 +71,24 @@
],
"paths": {
- "/rest/v1/short-urls": {
+ "/rest/v2/short-urls": {
"$ref": "paths/v1_short-urls.json"
},
- "/rest/v1/short-urls/shorten": {
+ "/rest/v2/short-urls/shorten": {
"$ref": "paths/v1_short-urls_shorten.json"
},
- "/rest/v1/short-urls/{shortCode}": {
+ "/rest/v2/short-urls/{shortCode}": {
"$ref": "paths/v1_short-urls_{shortCode}.json"
},
- "/rest/v1/short-urls/{shortCode}/tags": {
+ "/rest/v2/short-urls/{shortCode}/tags": {
"$ref": "paths/v1_short-urls_{shortCode}_tags.json"
},
- "/rest/v1/tags": {
+ "/rest/v2/tags": {
"$ref": "paths/v1_tags.json"
},
- "/rest/v1/short-urls/{shortCode}/visits": {
+ "/rest/v2/short-urls/{shortCode}/visits": {
"$ref": "paths/v1_short-urls_{shortCode}_visits.json"
},