openapi.yaml

openapi: '3.0.0'
info:
  version: 1.0.0
  title: Shorten URLs
  license:
    name: MIT
  contact:
    email: msroed@gmail.com
servers:
  - url: https://shorten.msroed.io/v1
tags:
  - name: shorten
paths:
  /:
    post:
      summary: Create a shortened URL
      operationId: createShortenedURL
      tags:
        - shorten
      requestBody:
        required: true
        content:
          application/json; charset=utf-8:
            schema:
              $ref: '#/components/schemas/ShortenRequest'
      responses:
        200:
          description: Success
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/ShortenResponse'
        400:
          description: Bad request format
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example: { 'message': 'Please send a valid URL' }
        409:
          description: Slug already taken
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example: { 'message': 'hello-world is already taken.' }
  /{slug}:
    get:
      summary: Resolve a slug
      operationId: resolveSlug
      description: Redirects to the url determined by the slug. Can respond with json if `noresponse` is set.
      tags:
        - shorten
      parameters:
        - name: slug
          in: path
          required: true
          description: The slug of the shortened url
          schema:
            type: string
          example: foo-bar
        - name: noredirect
          in: query
          description: Do not redirect, show json instead.
          required: false
          schema:
            type: boolean
            default: false
          example: false
      responses:
        200:
          description: Success
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  redirectUrl:
                    type: string
                example: { redirectUrl: 'https://some-obscure-url.com' }
        302:
          description: 'Redirect'
        404:
          $ref: '#/components/responses/NotFound'

components:
  responses:
    NotFound:
      description: This is not found
      content:
        application/json; charset=utf-8:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              { 'message': 'Can not find the resource you are asking for.' }

  schemas:
    ShortenRequest:
      required:
        - url
      properties:
        slug:
          type: string
        url:
          type: string
      example: { url: 'https://some-obscure-url.com/' }
    ShortenResponse:
      properties:
        shortenedUrl:
          type: string
        slug:
          type: string
      example:
        {
          'shortenedUrl': 'https://shorten.msroed.io/v1/foo-bar',
          'slug': 'foo-bar',
        }