onepixel.yaml

openapi: 3.1.0
info:
  version: '1.0'
  title: onepixel
  summary: 1px.li URL Shortner API
  description: 1px.li URL Shortner API
  contact:
    name: Arnav Gupta
    url: 'https://arnav.tech'
    email: dev@championswimmer.in
servers:
  - url: 'http://localhost:3000'
    description: dev
  - url: 'https://1px.li'
    description: prod
paths:
  '/{shorturl}':
    get:
      tags:
        - url
      summary: redirect to long url
      operationId: get-shorturl
      parameters:
        - $ref: '#/components/parameters/shorturl'
      responses:
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: The original long URL
        '404':
          description: Not Found
  /api/v1/users:
    post:
      tags:
        - user
      summary: create user
      description: create a new user
      operationId: post-api-v1-users
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user'
          application/xml:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/user'
      responses:
        '201':
          $ref: '#/components/responses/user-with-token'
        '422':
          $ref: '#/components/responses/422-unprocessable-entity'
        '409':
          $ref: '#/components/responses/409-conflict'

      security: []
  /api/v1/users/login:
    post:
      tags:
        - user
      summary: login user
      operationId: post-api-v1-users-login
      requestBody:
        $ref: '#/components/requestBodies/login-user-request'
      responses:
        '200':
          $ref: '#/components/responses/user-with-token'
  '/api/v1/users/{userid}':
    get:
      tags:
        - user
      summary: get user info
      description: get info about a user (needs to be self-authenticated)
      operationId: get-api-v1-users-userid
      parameters:
        - $ref: '#/components/parameters/userid'
      responses:
        '200':
          $ref: '#/components/responses/user-with-token'
        '401':
          $ref: '#/components/responses/401-unathorized'
        '403':
          $ref: '#/components/responses/403-forbidden'
      security:
        - bearerToken: []
    patch:
      tags:
        - user
      summary: update user
      description: update user info (needs to be self-authenticated)
      operationId: patch-api-v1-users-userid
      parameters:
        - $ref: '#/components/parameters/userid'
      requestBody:
        $ref: '#/components/requestBodies/login-user-request'
      responses:
        '200':
          $ref: '#/components/responses/user-with-token'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          $ref: '#/components/responses/403-forbidden'
      security:
        - bearerToken: []
  /api/v1/urls:
    post:
      tags:
        - url
      summary: create new short url
      operationId: post-api-v1-urls
      requestBody:
        $ref: '#/components/requestBodies/create-url-request'
      responses:
        '201':
          $ref: '#/components/responses/url-details'
      security:
        - bearerToken: []
  '/api/v1/urls/{shorturl}':
    get:
      tags:
        - url
      summary: get url details
      operationId: get-api-v1-urls-shorturl
      parameters:
        - $ref: '#/components/parameters/shorturl'
      responses:
        '200':
          $ref: '#/components/responses/url-details'
      security:
        - bearerToken: []
tags:
  - name: url
    description: things related to urls
  - name: user
    description: things related to users
components:
  parameters:
    userid:
      name: userid
      in: path
      required: true
      schema:
        type: integer
    shorturl:
      name: shorturl
      in: path
      required: true
      schema:
        type: string
        pattern: '^[A-Za-z-_]+'
        maxLength: 10
  requestBodies:
    login-user-request:
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
                format: email
              password:
                type: string
                format: password
    create-url-request:
      content:
        application/json:
          schema:
            type: object
            properties:
              longUrl:
                type: string
                format: uri
              groupId:
                type:
                  - integer
                  - 'null'
                format: int64
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
  responses:
    401-unathorized:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Example 1:
              value:
                code: 401
                message: unauthorised - please send bearer token
        application/xml:
          schema:
            $ref: '#/components/schemas/error'
    403-forbidden:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Example 1:
              value:
                code: 403
                message: forbidden - this resource is not available for current user
    422-unprocessable-entity:
      description: Unprocessable entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Example 1:
              value:
                code: 422
                message: "email and password are required to create user"
    409-conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
          examples:
            Example 1:
              value:
                code: 422
                message: "user with this email already exists"

    user-with-token:
      description: Example response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/user'
              - type: object
                properties:
                  token:
                    type: string
                    format: jwt
                    pattern: '^[A-Za-z0-9-_]*\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]*$'
                    readOnly: true
    url-details:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/url'
  schemas:
    user:
      type: object
      title: user
      description: users of the project
      properties:
        id:
          type: integer
          format: int64
          readOnly: true
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
          writeOnly: true
    error:
      type: object
      title: error
      description: error
      properties:
        code:
          type: integer
          format: int32
          readOnly: true
        message:
          type: string
    url:
      type: object
      title: url
      description: the shortened url and the original URL is points to
      properties:
        id:
          type: string
          pattern: '[A-Za-z0-9-_]+'
          maxLength: 10
        longUrl:
          type: string
        groupId:
          type:
            - integer
            - 'null'
          format: int64
        creator:
          $ref: '#/components/schemas/user'