Skip to content

Commit

Permalink
Merge pull request #182 from YashKumarVerma/issue-168-api-docs
Browse files Browse the repository at this point in the history 
API Docs added
  • Loading branch information
@championswimmer
championswimmer authored Aug 21, 2020
2 parents 95ad698 + c3b4fce commit c6395c0
Show file tree
Hide file tree
Showing 5 changed files with 234 additions and 1 deletion.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,8 @@ typings/
# next.js build output
.next

docs

# IDEs
.idea/
.vscode/
Expand Down
8 changes: 8 additions & 0 deletions apidoc.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"name": "Coding Blocks Shortlr2 API",
"version": "0.1.0",
"description": "API for the in Shortlr2 Project",
"template": {
"forceLanguage": "en"
}
}
2 changes: 2 additions & 0 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"license": "MIT",
"private": false,
"dependencies": {
"apidocs": "^2017.3.9",
"connect-ensure-login": "^0.1.1",
"connect-session-sequelize": "^6.0.0",
"convert-radix64": "^0.2.0",
Expand Down Expand Up @@ -41,6 +42,7 @@
"watch": "nodemon --watch src -e js,ts --exec 'export NODE_PATH=dist && node dist/run.js'",
"test": "mocha",
"cover": "nyc mocha",
"docs": "apidoc -i src/routes/api/ -o docs/",
"migrate": "ts-node ./src/scripts/migrate.js"
},
"devDependencies": {
Expand Down
218 changes: 217 additions & 1 deletion src/routes/api/url.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,51 @@ import { optsFromGroupedShortcode } from '../../utils/shortener'

export const route = Router()

/**
* @api {get} api/urls/:shortCode Details of URL not part of a group
* @apiVersion 0.1.0
* @apiGroup Short URL Operations
* @apiName Get shorturl info
* @apiPermission BearerToken
* @apiHeader {String} Authorization bearerToken token from oneAuth
* @apiDescription This endpoint returns all the data about a short code passed as param. If a suitable
* shortcode is not matched, then the application checks if a group with the passed shortCode exists
*
* @apiParam {String} shortCode The short url the detail of which is required
*
* @apiSuccess (Short Url Details) {Object} Object containing all the details of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.id unique internal id of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.code string containing a big integer code
* @apiSuccess (Short Url Details) {Number} Object.codeStr string received by the application to process shortcode
* @apiSuccess (Short Url Details) {Number} Object.codeActual the actual short code, after removing group name
* @apiSuccess (Short Url Details) {String} Object.longUrl the url which the short code points to
* @apiSuccess (Short Url Details) {Number} Object.hits number of times the passed url is opened
* @apiSuccess (Short Url Details) {Boolean} Object.private true if the url is a private url, false if it is not
* @apiSuccess (Short Url Details) {Number} Object.ownerId the id of the user who created the shortcode
* @apiSuccess (Short Url Details) {String} Object.groupId the group to which url belongs, null if no group present
* @apiSuccess (Short Url Details) {Date} Object.createdAt data when the shortcode was created
* @apiSuccess (Short Url Details) {Date} Object.updatedAt data when the shortcode was updated
* @apiSuccess (Short Url Details) {Date} Object.deletedAt data when the shortcode was deleted, by default null
*
* @apiErrorExample {application/json} Error-Response:
* {"error":"Could not find shortcode."}
* @apiExample {json} Example Response:
* {
* "id":1,
* "code":"79542000",
* "codeStr":"4lRcW",
* "codeActual":"4lRcW",
* "longUrl":"https://github.com/yashkumarverma/?utm_source=Testing&utm_medium=manual&utm_campaign=testing_campaign",
* "hits":0,
* "private":false,
* "ownerId":24XXXX,
* "groupId":null,
* "createdAt":"2020-05-29T08:33:07.224Z",
* "updatedAt":"2020-05-29T08:33:07.224Z",
* "deletedAt":null
* }
*
*/
route.get('/:code', async (req, res) => {
try {
const url = await findUrlByShortcode(req.params.code)
Expand All @@ -23,6 +68,68 @@ route.get('/:code', async (req, res) => {
}
})

/**
* @api {get} api/urls/:group List all urls of Group
* @apiVersion 0.1.0
* @apiGroup Short URL Operations
* @apiName Get details of all short-codes belonging to a group
* @apiPermission BearerToken
* @apiHeader {String} Authorization bearerToken token from oneAuth
* @apiDescription This endpoint returns an array containing details of all short-codes belonging to a group
*
* @apiParam {String} group the name of the group whose details are required
*
* @apiSuccess (Short Url Details) {Object[]} Array array of objects containing details of the member shortcodes
* @apiSuccess (Short Url Details) {Object} Array.Object containing all the details of the url shortcode
* @apiSuccess (Short Url Details) {Number} Array.Object.id unique internal id of the url shortcode
* @apiSuccess (Short Url Details) {Number} Array.Object.code string containing a big integer code
* @apiSuccess (Short Url Details) {Number} Array.Object.codeStr string received by the application to process shortcode
* @apiSuccess (Short Url Details) {Number} Array.Object.codeActual the actual short code, after removing group name
* @apiSuccess (Short Url Details) {String} Array.Object.longUrl the url which the short code points to
* @apiSuccess (Short Url Details) {Number} Array.Object.hits number of times the passed url is opened
* @apiSuccess (Short Url Details) {Boolean} Array.Object.private true if the url is a private url, false if it is not
* @apiSuccess (Short Url Details) {Number} Array.Object.ownerId the id of the user who created the shortcode
* @apiSuccess (Short Url Details) {String} Array.Object.groupId the group to which url belongs, null if no group present
* @apiSuccess (Short Url Details) {Date} Array.Object.createdAt data when the shortcode was created
* @apiSuccess (Short Url Details) {Date} Array.Object.updatedAt data when the shortcode was updated
* @apiSuccess (Short Url Details) {Date} Array.Object.deletedAt data when the shortcode was deleted, by default null
*
* @apiErrorExample {application/json} Error-Response:
* {"error":"Could not find shortcode."}
*
* @apiExample {json} Listing all urls of a group
* [
* {
* "id":13,
* "code":"469276379205632",
* "codeStr":"1github00",
* "codeActual":"boss/github",
* "longUrl":"https://github.com/coding-blocks/boss",
* "hits":0,
* "private":false,
* "ownerId":24XXXX,
* "groupId":1,
* "createdAt":"2020-05-29T13:16:21.447Z",
* "updatedAt":"2020-05-29T13:16:21.447Z",
* "deletedAt":null
* },
* {
* "id":14,
* "code":"539351099603456",
* "codeStr":"1website0",
* "codeActual":"boss/website",
* "longUrl":"https://boss.codingblocks.com/",
* "hits":0,
* "private":false,
* "ownerId":24XXXX,
* "groupId":1,
* "createdAt":"2020-05-29T14:19:46.611Z",
* "updatedAt":"2020-05-29T14:19:46.611Z",
* "deletedAt":null
* }
* ]
*
*/
route.get('/:group', async (req, res) => {
try {
const urls = await findUrlsInGroup(req.params.group)
Expand All @@ -36,6 +143,52 @@ route.get('/:group', async (req, res) => {
}
})

/**
* @api {get} api/urls/:group/:shortCode Details of URL part of a group
* @apiVersion 0.1.0
* @apiGroup Short URL Operations
* @apiName Get info of shortcode belonging to a group
* @apiPermission BearerToken
* @apiHeader {String} Authorization bearerToken token from oneAuth
* @apiDescription This endpoint returns data of short-url belonging to a group
*
* @apiParam {String} group the name of the group to which the short-url belongs
* @apiParam {String} shortCode the shortcode whose details are required
*
* @apiSuccess (Short Url Details) {Object} Object containing all the details of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.id unique internal id of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.code string containing a big integer code
* @apiSuccess (Short Url Details) {Number} Object.codeStr string received by the application to process shortcode
* @apiSuccess (Short Url Details) {Number} Object.codeActual the actual short code, after removing group name
* @apiSuccess (Short Url Details) {String} Object.longUrl the url which the short code points to
* @apiSuccess (Short Url Details) {Number} Object.hits number of times the passed url is opened
* @apiSuccess (Short Url Details) {Boolean} Object.private true if the url is a private url, false if it is not
* @apiSuccess (Short Url Details) {Number} Object.ownerId the id of the user who created the shortcode
* @apiSuccess (Short Url Details) {String} Object.groupId the group to which url belongs, null if no group present
* @apiSuccess (Short Url Details) {Date} Object.createdAt data when the shortcode was created
* @apiSuccess (Short Url Details) {Date} Object.updatedAt data when the shortcode was updated
* @apiSuccess (Short Url Details) {Date} Object.deletedAt data when the shortcode was deleted, by default null
*
* @apiErrorExample {application/json} Error-Response:
* {"error":"Could not find shortcode."}
*
* @apiExample {json} When requesting data of short-code:github of group:boss
* {
* "id":13,
* "code":"469276379205632",
* "codeStr":"1github00",
* "codeActual":"boss/github",
* "longUrl":"https://github.com/coding-blocks/boss",
* "hits":250,
* "private":false,
* "ownerId":24XXXX,
* "groupId":1,
* "updatedAt":"2020-05-29T13:16:21.447Z",
* "createdAt":"2020-05-29T13:16:21.447Z",
* "deletedAt":null
* }
*
*/
route.get('/:group/:code', async (req, res) => {
try {
const group = await findGroupByPrefix(req.params.group)
Expand All @@ -51,13 +204,76 @@ route.get('/:group/:code', async (req, res) => {
}
})

/**
* @api {post} api/urls/ Create New Short URL
* @apiVersion 0.1.0
* @apiGroup Short URL Operations
* @apiName Generate Short URL
* @apiPermission BearerToken
* @apiHeader {String} Authorization bearerToken token from oneAuth
* @apiDescription This endpoint is used to create short URLs.
*
* @apiParam {String} longUrl the long url to be shortened
* @apiParam {String} [shortCode] the custom shortcode required for the passed url. To create groups,
* use the format <groupName>/<shortCode>
* @apiParam {Boolean} [private] true if user should login to access the link, false for not
*
* @apiSuccess (Short Url Details) {Object} Object containing all the details of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.id unique internal id of the url shortcode
* @apiSuccess (Short Url Details) {Number} Object.code string containing a big integer code
* @apiSuccess (Short Url Details) {Number} Object.codeStr string received by the application to process shortcode
* @apiSuccess (Short Url Details) {Number} Object.codeActual the actual short code, after removing group name
* @apiSuccess (Short Url Details) {String} Object.longUrl the url which the short code points to
* @apiSuccess (Short Url Details) {Number} Object.hits number of times the passed url is opened
* @apiSuccess (Short Url Details) {Boolean} Object.private true if the url is a private url, false if it is not
* @apiSuccess (Short Url Details) {Number} Object.ownerId the id of the user who created the shortcode
* @apiSuccess (Short Url Details) {String} Object.groupId the group to which url belongs, null if no group present
* @apiSuccess (Short Url Details) {Date} Object.createdAt data when the shortcode was created
* @apiSuccess (Short Url Details) {Date} Object.updatedAt data when the shortcode was updated
* @apiSuccess (Short Url Details) {Date} Object.deletedAt data when the shortcode was deleted, by default null
*
* @apiErrorExample {application/json} Error-Response:
* {"error":"Could not find shortcode."}
*
* @apiExample {json} When creating entry not belonging to group
* {
* "id":1,
* "code":"79542000",
* "codeStr":"4lRcW",
* "codeActual":"4lRcW",
* "longUrl":"https://github.com/yashkumarverma/?utm_source=Testing&utm_medium=manual&utm_campaign=testing_campaign",
* "hits":21,
* "private":false,
* "ownerId":24XXXX,
* "groupId":null,
* "createdAt":"2020-05-29T08:33:07.224Z",
* "updatedAt":"2020-05-29T08:33:07.224Z",
* "deletedAt":null
* }
*
* @apiExample {json} When creating entry belonging to group
* {
* "id":13,
* "code":"469276379205632",
* "codeStr":"1github00",
* "codeActual":"boss/github",
* "longUrl":"https://github.com/coding-blocks/boss",
* "hits":250,
* "private":false,
* "ownerId":24XXXX,
* "groupId":1,
* "createdAt":"2020-05-29T13:16:21.447Z",
* "updatedAt":"2020-05-29T13:16:21.447Z",
* "deletedAt":null
* }
*
*/
route.post('/', async (req, res) => {
try {
const url = await createUrl(
{
longUrl: req.body.longUrl,
shortCode: req.body.shortCode,
private: req.body.private,
},
req.user,
)
Expand Down
5 changes: 5 additions & 0 deletions yarn.lock
View file
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,11 @@ ansi-styles@^3.2.1:
dependencies:
color-convert "^1.9.0"

apidocs@^2017.3.9:
version "2017.3.9"
resolved "https://registry.yarnpkg.com/apidocs/-/apidocs-2017.3.9.tgz#e417d46e80a2d8c4acebcadfc487b82c0ef18c22"
integrity sha1-5BfUboCi2MSs68rfxIe4LA7xjCI=

append-transform@^1.0.0:
version "1.0.0"
resolved "https://registry.yarnpkg.com/append-transform/-/append-transform-1.0.0.tgz#046a52ae582a228bd72f58acfbe2967c678759ab"
Expand Down

0 comments on commit c6395c0

Please sign in to comment.