318 lines
7.8 KiB
YAML
318 lines
7.8 KiB
YAML
|
openapi: "3.0.2"
|
||
|
info:
|
||
|
version: 1.0.0
|
||
|
title: GoShort API
|
||
|
description: Interact with shorts directly via the API.
|
||
|
license:
|
||
|
name: AGPL 3.0
|
||
|
url: https://www.gnu.org/licenses/agpl-3.0.en.html
|
||
|
servers:
|
||
|
- url: /api
|
||
|
description: The API server
|
||
|
tags:
|
||
|
- name: User
|
||
|
description: Current user
|
||
|
- name: Shorts
|
||
|
description: Short management
|
||
|
- name: Short Logs
|
||
|
description: Short access logs
|
||
|
x-tagGroups:
|
||
|
- name: User
|
||
|
tags:
|
||
|
- User
|
||
|
- name: Shorts
|
||
|
tags:
|
||
|
- Shorts
|
||
|
- Short Logs
|
||
|
paths:
|
||
|
/me:
|
||
|
get:
|
||
|
summary: Get user
|
||
|
description: Returns the current user's info
|
||
|
operationId: me
|
||
|
tags:
|
||
|
- User
|
||
|
responses:
|
||
|
"200":
|
||
|
description: OK
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/User"
|
||
|
"401":
|
||
|
$ref: "#/components/responses/Unauthorized"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
|
||
|
/shorts:
|
||
|
get:
|
||
|
summary: List shorts
|
||
|
description: Lists all shorts belonging to the current user
|
||
|
operationId: listShorts
|
||
|
security:
|
||
|
- Token: []
|
||
|
tags:
|
||
|
- Shorts
|
||
|
responses:
|
||
|
"200":
|
||
|
description: OK
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
type: array
|
||
|
items:
|
||
|
$ref: "#/components/schemas/Short"
|
||
|
"401":
|
||
|
$ref: "#/components/responses/Unauthorized"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
post:
|
||
|
summary: Create short
|
||
|
description: Creates a new short for the current user
|
||
|
operationId: createShort
|
||
|
tags:
|
||
|
- Shorts
|
||
|
requestBody:
|
||
|
description: Short to create
|
||
|
required: true
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/NewShort"
|
||
|
responses:
|
||
|
"201":
|
||
|
description: Created
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/Short"
|
||
|
"400":
|
||
|
$ref: "#/components/responses/BadRequest"
|
||
|
"401":
|
||
|
$ref: "#/components/responses/Unauthorized"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
|
||
|
/shorts/{id}:
|
||
|
get:
|
||
|
summary: Find short
|
||
|
description: Returns a single short by its ID
|
||
|
operationId: getShort
|
||
|
tags:
|
||
|
- Shorts
|
||
|
parameters:
|
||
|
- name: id
|
||
|
in: path
|
||
|
description: ID of the short to get
|
||
|
required: true
|
||
|
schema:
|
||
|
type: string
|
||
|
responses:
|
||
|
"200":
|
||
|
description: OK
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/Short"
|
||
|
"404":
|
||
|
$ref: "#/components/responses/NotFound"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
delete:
|
||
|
summary: Delete short
|
||
|
description: Deletes a short by its ID
|
||
|
operationId: deleteShort
|
||
|
tags:
|
||
|
- Shorts
|
||
|
parameters:
|
||
|
- name: id
|
||
|
in: path
|
||
|
description: ID of the short to delete
|
||
|
required: true
|
||
|
schema:
|
||
|
type: string
|
||
|
responses:
|
||
|
"204":
|
||
|
description: No Content
|
||
|
"404":
|
||
|
$ref: "#/components/responses/NotFound"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
|
||
|
/shorts/{id}/logs:
|
||
|
get:
|
||
|
summary: List short views
|
||
|
description: Lists all views of a short
|
||
|
operationId: listShortLogs
|
||
|
tags:
|
||
|
- Short Logs
|
||
|
parameters:
|
||
|
- name: id
|
||
|
in: path
|
||
|
description: ID of the short to get logs for
|
||
|
required: true
|
||
|
schema:
|
||
|
type: string
|
||
|
responses:
|
||
|
"200":
|
||
|
description: OK
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
type: array
|
||
|
items:
|
||
|
$ref: "#/components/schemas/ShortLog"
|
||
|
"404":
|
||
|
$ref: "#/components/responses/NotFound"
|
||
|
default:
|
||
|
$ref: "#/components/responses/InternalServerError"
|
||
|
security:
|
||
|
- Token: []
|
||
|
components:
|
||
|
schemas:
|
||
|
User:
|
||
|
type: object
|
||
|
required:
|
||
|
- id
|
||
|
- username
|
||
|
- createdAt
|
||
|
properties:
|
||
|
id:
|
||
|
type: string
|
||
|
example: abc123
|
||
|
username:
|
||
|
type: string
|
||
|
format: email
|
||
|
example: user@example.com
|
||
|
createdAt:
|
||
|
type: string
|
||
|
format: date-time
|
||
|
example: 2020-01-01T00:00:00Z
|
||
|
Short:
|
||
|
type: object
|
||
|
allOf:
|
||
|
- $ref: "#/components/schemas/NewShort"
|
||
|
- required:
|
||
|
- id
|
||
|
- url
|
||
|
- name
|
||
|
- shorturl
|
||
|
- createdAt
|
||
|
properties:
|
||
|
id:
|
||
|
description: ID of the short
|
||
|
type: string
|
||
|
example: abc123
|
||
|
shorturl:
|
||
|
description: Short URL
|
||
|
type: string
|
||
|
format: url
|
||
|
example: https://goshort.com/my-short-url
|
||
|
createdAt:
|
||
|
description: Creation date
|
||
|
type: string
|
||
|
format: date-time
|
||
|
example: 2020-01-01T00:00:00Z
|
||
|
NewShort:
|
||
|
type: object
|
||
|
required:
|
||
|
- url
|
||
|
properties:
|
||
|
url:
|
||
|
description: URL the short redirects to
|
||
|
type: string
|
||
|
format: url
|
||
|
example: https://my.example.com/very/long/url
|
||
|
name:
|
||
|
description: Name of the short, defines the short URL
|
||
|
type: string
|
||
|
example: my-short-url
|
||
|
ShortLog:
|
||
|
type: object
|
||
|
required:
|
||
|
- id
|
||
|
- shortID
|
||
|
- ipAddress
|
||
|
- userAgent
|
||
|
- referer
|
||
|
- createdAt
|
||
|
properties:
|
||
|
id:
|
||
|
type: string
|
||
|
description: ID of the access log
|
||
|
example: abc123
|
||
|
shortID:
|
||
|
type: string
|
||
|
description: ID of the short
|
||
|
example: abc123
|
||
|
ipAddress:
|
||
|
type: string
|
||
|
description: IP address of the client
|
||
|
format: ip
|
||
|
example: 1.1.1.1
|
||
|
userAgent:
|
||
|
type: string
|
||
|
description: User agent of the client
|
||
|
example: Mozilla/5.0 (X11; Linux x86_64; rv:72.0) Gecko/20100101 Firefox/72.0
|
||
|
referer:
|
||
|
type: string
|
||
|
description: Referer of the client
|
||
|
format: url
|
||
|
example: https://my.referer.com
|
||
|
createdAt:
|
||
|
type: string
|
||
|
format: date-time
|
||
|
description: Creation date
|
||
|
example: 2020-01-01T00:00:00Z
|
||
|
Error:
|
||
|
type: object
|
||
|
required:
|
||
|
- status
|
||
|
- error
|
||
|
properties:
|
||
|
status:
|
||
|
type: string
|
||
|
error:
|
||
|
type: string
|
||
|
responses:
|
||
|
NotFound:
|
||
|
description: The specified resource was not found
|
||
|
content:
|
||
|
text/plain:
|
||
|
schema:
|
||
|
type: string
|
||
|
Unauthorized:
|
||
|
description: Your credentials were missing or incorrect
|
||
|
content:
|
||
|
text/plain:
|
||
|
schema:
|
||
|
type: string
|
||
|
Forbidden:
|
||
|
description: You do not have permission to access this resource
|
||
|
content:
|
||
|
text/plain:
|
||
|
schema:
|
||
|
type: string
|
||
|
BadRequest:
|
||
|
description: Your request was not understood by the server
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/Error"
|
||
|
InternalServerError:
|
||
|
description: An unexpected error occurred
|
||
|
content:
|
||
|
application/json:
|
||
|
schema:
|
||
|
$ref: "#/components/schemas/Error"
|
||
|
securitySchemes:
|
||
|
Token:
|
||
|
type: http
|
||
|
scheme: bearer
|
||
|
description: |
|
||
|
The token to authenticate with. It must be sent in the Authorization header as a Bearer token.
|
||
|
|
||
|
Example:
|
||
|
|
||
|
`Authorization: Bearer <your-token>`
|