shlink/docs/swagger.json

{
    "swagger": "2.0",
    "info": {
        "title": "Shlink",
        "description": "Shlink, the self-hosted URL shortener",
        "version": "1.2.0"
    },
    "schemes": [
        "https"
    ],
    "basePath": "/rest",
    "produces": [
        "application/json"
    ],

    "paths": {
        "/authenticate": {
            "post": {
                "description": "Performs an authentication",
                "parameters": [
                    {
                        "name": "apiKey",
                        "in": "formData",
                        "description": "The API key to authenticate with",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The authentication worked.",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "token": {
                                    "type": "string",
                                    "description": "The authentication token that needs to be sent in the Authorization header"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "An API key was not provided.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "401": {
                        "description": "The API key is incorrect, is disabled or has expired.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/short-codes": {
            "get": {
                "description": "Returns the list of short codes",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "description": "The page to be displayed. Defaults to 1",
                        "required": false,
                        "type": "integer"
                    },
                    {
                        "name": "searchTerm",
                        "in": "query",
                        "description": "A query used to filter results by searching for it on the longUrl and shortCode fields. (From Shlink 1.3.0)",
                        "required": false,
                        "type": "string"
                    },
                    {
                        "$ref": "#/parameters/Authorization"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The list of short URLs",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "shortUrls": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/definitions/ShortUrl"
                                            }
                                        },
                                        "pagination": {
                                            "$ref": "#/definitions/Pagination"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            },
            "post": {
                "description": "Creates a new short code",
                "parameters": [
                    {
                        "name": "longUrl",
                        "in": "formData",
                        "description": "The URL to parse",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "tags",
                        "in": "formData",
                        "description": "The URL to parse",
                        "required": false,
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    {
                        "$ref": "#/parameters/Authorization"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The result of parsing the long URL",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "longUrl": {
                                    "type": "string",
                                    "description": "The original long URL that has been parsed"
                                },
                                "shortUrl": {
                                    "type": "string",
                                    "description": "The generated short URL"
                                },
                                "shortCode": {
                                    "type": "string",
                                    "description": "the short code that is being used in the short URL"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The long URL was not provided or is invalid.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/short-codes/{shortCode}": {
            "get": {
                "description": "Get the long URL behind a short code.",
                "parameters": [
                    {
                        "name": "shortCode",
                        "in": "path",
                        "type": "string",
                        "description": "The short code to resolve.",
                        "required": true
                    },
                    {
                        "$ref": "#/parameters/Authorization"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The long URL behind a short code.",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "longUrl": {
                                    "type": "string",
                                    "description": "The original long URL behind the short code."
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Provided shortCode does not match the character set currently used by the app to generate short codes.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "404": {
                        "description": "No URL was found for provided short code.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/short-codes/{shortCode}/visits": {
            "get": {
                "description": "Get the list of visits on provided short code.",
                "parameters": [
                    {
                        "name": "shortCode",
                        "in": "path",
                        "type": "string",
                        "description": "The shortCode from which we want to get the visits.",
                        "required": true
                    },
                    {
                        "$ref": "#/parameters/Authorization"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of visits.",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "visits": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/definitions/Visit"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The short code does not belong to any short URL.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        },
        "/short-codes/{shortCode}/tags": {
            "put": {
                "description": "Edit the tags on provided short code.",
                "parameters": [
                    {
                        "name": "shortCode",
                        "in": "path",
                        "type": "string",
                        "description": "The shortCode in which we want to edit tags.",
                        "required": true
                    },
                    {
                        "name": "tags",
                        "in": "formData",
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "The list of tags to set to the short URL.",
                        "required": true
                    },
                    {
                        "$ref": "#/parameters/Authorization"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of tags.",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "tags": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request body does not contain a \"tags\" param with array type.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "404": {
                        "description": "No short URL was found for provided short code.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    },
                    "500": {
                        "description": "Unexpected error.",
                        "schema": {
                            "$ref": "#/definitions/Error"
                        }
                    }
                }
            }
        }
    },

    "definitions": {
        "ShortUrl": {
            "type": "object",
            "properties": {
                "shortCode": {
                    "type": "string",
                    "description": "The short code for this short URL."
                },
                "originalUrl": {
                    "type": "string",
                    "description": "The original long URL."
                },
                "dateCreated": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The date in which the short URL was created in ISO format."
                },
                "visitsCount": {
                    "type": "integer",
                    "description": "The number of visits that this short URL has recieved."
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "A list of tags applied to this short URL"
                }
            }
        },
        "Visit": {
            "type": "object",
            "properties": {
                "referer": {
                    "type": "string"
                },
                "date": {
                    "type": "string",
                    "format": "date-time"
                },
                "remoteAddr": {
                    "type": "string"
                },
                "userAgent": {
                    "type": "string"
                }
            }
        },
        "Error": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "string",
                    "description": "A machine unique code"
                },
                "message": {
                    "type": "string",
                    "description": "A human-friendly error message"
                }
            }
        },
        "Pagination": {
            "type": "object",
            "properties": {
                "currentPage": {
                    "type": "integer",
                    "description": "The number of current page being displayed."
                },
                "pagesCount": {
                    "type": "integer",
                    "description": "The total number of pages that can be displayed."
                }
            }
        }
    },

    "parameters": {
        "Authorization": {
            "name": "Authorization",
            "in": "header",
            "description": "The authorization token with Bearer type",
            "required": true,
            "type": "string"
        }
    }
}