Skip to content

Instantly share code, notes, and snippets.

@char0n

char0n/openapi-3-1.json

Created November 14, 2023 13:06
Show Gist options
  • Save char0n/ccdad0913c14b75ba45580850922692f to your computer and use it in GitHub Desktop.
Save char0n/ccdad0913c14b75ba45580850922692f to your computer and use it in GitHub Desktop.
Download ZIP
Raw
openapi-3-1.json
{
"openapi": "3.1.0",
"info": {
"title": "Shlink",
"description": "Shlink, the self-hosted URL shortener",
"version": "3.0"
},
"servers": [
{
"url": "{scheme}:\/\/{host}",
"variables": {
"scheme": {
"enum": [
"https",
"http"
],
"default": "https"
},
"host": {
"default": ""
}
}
}
],
"paths": {
"\/rest\/v{version}\/short-urls": {
"get": {
"tags": [
"Short URLs"
],
"summary": "List short URLs",
"description": "Returns the list of short URLs.",
"operationId": "listShortUrls",
"parameters": [
{
"name": "version",
"in": "path",
"description": "The API version to be consumed",
"required": true,
"schema": {
"enum": [
"3",
"2",
"1"
],
"type": "string"
}
},
{
"name": "page",
"in": "query",
"description": "The page to be displayed. Defaults to 1",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "itemsPerPage",
"in": "query",
"description": "The amount of items to return on every page. Defaults to 10",
"required": false,
"schema": {
"type": "number"
}
},
{
"name": "searchTerm",
"in": "query",
"description": "A query used to filter results by searching for it on the longUrl and shortCode fields. (Since v1.3.0)",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "tags[]",
"in": "query",
"description": "A list of tags used to filter the result set. Only short URLs tagged with at least one of the provided tags will be returned. (Since v1.3.0)",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "tagsMode",
"in": "query",
"description": "Tells how the filtering by tags should work, returning short URLs containing \"any\" of the tags, or \"all\" the tags. It's ignored if no tags are provided, and defaults to \"any\" if not provided.",
"required": false,
"schema": {
"enum": [
"any",
"all"
],
"type": "string"
}
},
{
"name": "orderBy",
"in": "query",
"description": "The field from which you want to order the result.",
"required": false,
"schema": {
"enum": [
"longUrl-ASC",
"longUrl-DESC",
"shortCode-ASC",
"shortCode-DESC",
"dateCreated-ASC",
"dateCreated-DESC",
"title-ASC",
"title-DESC",
"visits-ASC",
"visits-DESC",
"nonBotVisits-ASC",
"nonBotVisits-DESC"
],
"type": "string"
}
},
{
"name": "startDate",
"in": "query",
"description": "The date (in ISO-8601 format) from which we want to get short URLs.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "endDate",
"in": "query",
"description": "The date (in ISO-8601 format) until which we want to get short URLs.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "excludeMaxVisitsReached",
"in": "query",
"description": "If true, short URLs which already reached their maximum amount of visits will be excluded.",
"required": false,
"schema": {
"enum": [
"true",
"false"
],
"type": "string"
}
},
{
"name": "excludePastValidUntil",
"in": "query",
"description": "If true, short URLs which validUntil date is on the past will be excluded.",
"required": false,
"schema": {
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The list of short URLs",
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"shortUrls": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"required": [
"shortCode",
"shortUrl",
"longUrl",
"deviceLongUrls",
"dateCreated",
"visitsCount",
"visitsSummary",
"tags",
"meta",
"domain",
"title",
"crawlable",
"forwardQuery"
],
"type": "object",
"properties": {
"shortCode": {
"type": "string",
"description": "The short code for this short URL."
},
"shortUrl": {
"type": "string",
"description": "The short URL."
},
"longUrl": {
"type": "string",
"description": "The original long URL."
},
"deviceLongUrls": {
"required": [
"android",
"ios",
"desktop"
],
"type": "object",
"allOf": [
{
"type": "object",
"allOf": [
{
"type": "object",
"properties": {
"android": {
"type": [
"string"
],
"description": "The long URL to redirect to when the short URL is visited from a device running Android"
},
"ios": {
"type": [
"string"
],
"description": "The long URL to redirect to when the short URL is visited from a device running iOS"
},
"desktop": {
"type": [
"string"
],
"description": "The long URL to redirect to when the short URL is visited from a desktop browser"
}
}
}
],
"properties": {
"android": {
"type": [
"null"
]
},
"ios": {
"type": [
"null"
]
},
"desktop": {
"type": [
"null"
]
}
}
}
]
},
"dateCreated": {
"type": "string",
"description": "The date in which the short URL was created in ISO format.",
"format": "date-time"
},
"visitsCount": {
"type": "integer",
"description": "**[DEPRECATED]** Use `visitsSummary.total` instead.",
"deprecated": true
},
"visitsSummary": {
"required": [
"total",
"nonBots",
"bots"
],
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "The total amount of visits."
},
"nonBots": {
"type": "integer",
"description": "The amount of visits which were not identified as bots."
},
"bots": {
"type": "integer",
"description": "The amount of visits that were identified as potential bots."
}
}
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of tags applied to this short URL"
},
"meta": {
"required": [
"validSince",
"validUntil",
"maxVisits"
],
"type": "object",
"properties": {
"validSince": {
"type": [
"string",
"null"
],
"description": "The date (in ISO-8601 format) from which this short code will be valid"
},
"validUntil": {
"type": [
"string",
"null"
],
"description": "The date (in ISO-8601 format) until which this short code will be valid"
},
"maxVisits": {
"type": [
"number",
"null"
],
"description": "The maximum number of allowed visits for this short code"
}
}
},
"domain": {
"type": [
"string",
"null"
],
"description": "The domain in which the short URL was created. Null if it belongs to default domain."
},
"title": {
"type": [
"string",
"null"
],
"description": "A descriptive title of the short URL."
},
"crawlable": {
"type": "boolean",
"description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt."
},
"forwardQuery": {
"type": "boolean",
"description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)."
}
}
}
},
"pagination": {
"type": "object",
"properties": {
"currentPage": {
"type": "integer",
"description": "The number of current page."
},
"pagesCount": {
"type": "integer",
"description": "The total number of pages that can be obtained."
},
"itemsPerPage": {
"type": "integer",
"description": "The number of items for every page."
},
"itemsInCurrentPage": {
"type": "integer",
"description": "The number of items in current page (could be smaller than itemsPerPage)."
},
"totalItems": {
"type": "integer",
"description": "The total number of items among all pages."
}
}
}
}
}
}
},
"example": {
"shortUrls": {
"data": [
{
"shortCode": "12C18",
"shortUrl": "https:\/\/s.test\/12C18",
"longUrl": "https:\/\/store.steampowered.com",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"dateCreated": "2016-08-21T20:34:16+02:00",
"visitsSummary": {
"total": 328,
"nonBots": 328,
"bots": 0
},
"tags": [
"games",
"tech"
],
"meta": {
"validSince": "2017-01-21T00:00:00+02:00",
"validUntil": null,
"maxVisits": 100
},
"domain": null,
"title": "Welcome to Steam",
"crawlable": false
},
{
"shortCode": "12Kb3",
"shortUrl": "https:\/\/s.test\/12Kb3",
"longUrl": "https:\/\/shlink.io",
"deviceLongUrls": {
"android": null,
"ios": "https:\/\/shlink.io\/ios",
"desktop": null
},
"dateCreated": "2016-05-01T20:34:16+02:00",
"visitsSummary": {
"total": 1029,
"nonBots": 900,
"bots": 129
},
"tags": [
"shlink"
],
"meta": {
"validSince": null,
"validUntil": null,
"maxVisits": null
},
"domain": null,
"title": null,
"crawlable": false
},
{
"shortCode": "123bA",
"shortUrl": "https:\/\/example.com\/123bA",
"longUrl": "https:\/\/www.google.com",
"deviceLongUrls": {
"android": null,
"ios": null,
"desktop": null
},
"dateCreated": "2015-10-01T20:34:16+02:00",
"visitsSummary": {
"total": 25,
"nonBots": 0,
"bots": 25
},
"tags": [],
"meta": {
"validSince": "2017-01-21T00:00:00+02:00",
"validUntil": null,
"maxVisits": null
},
"domain": "example.com",
"title": null,
"crawlable": false
}
],
"pagination": {
"currentPage": 5,
"pagesCount": 12,
"itemsPerPage": 10,
"itemsInCurrentPage": 10,
"totalItems": 115
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application\/problem+json": {
"schema": {
"required": [
"type",
"title",
"detail",
"status"
],
"type": "object",
"properties": {
"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"
}
}
}
}
}
}
},
"security": [
{
"ApiKey": []
}
]
}
}
},
"components": {
"securitySchemes": {
"ApiKey": {
"type": "apiKey",
"description": "A valid shlink API key",
"name": "X-Api-Key",
"in": "header"
}
}
},
"tags": [
{
"name": "Short URLs",
"description": "Operations that can be performed on short URLs"
}
],
"externalDocs": {
"description": "Find more info on how to start using this API here",
"url": "https:\/\/shlink.io\/documentation\/api-docs"
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment