openapi.yaml

openapi: 3.0.1
info:
  title: guitar-composer API
  description: |-
    ***Guitar Composer*** is a platform for guitarists.\
    The intent is to make songs lyrics with chords, public to anyone.\
    Join for free to upload new songs.
  version: "1.0"
  contact:
    email: alexbernardi360@gmail.com
    name: Alessandro Bernardi
  license:
    url: https://opensource.org/licenses/MIT
    name: MIT
servers:
  - url: 'https://guitar-composer.herokuapp.com/'
paths:
  /api/join:
    post:
      description: Registration to the platform
      parameters:
        - name: username
          in: header
          schema:
            type: string
          example: Hummingbird
        - name: password
          in: header
          schema:
            type: string
          example: passWord_1
      responses:
        '200':
          description: Registration successful
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Hummingbird, registration successful.
        '422':
          description: Username or password errors
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              examples:
                'username error':
                  value: Username not available.
                'password error':
                  value: Wrong password format.
      tags:
        - Account management
  /api/deleteAccount:
    delete:
      description: Delete your personal account
      parameters:
        - name: username
          in: header
          schema:
            type: string
          example: Hummingbird
        - name: password
          in: header
          schema:
            type: string
          example: passWord_1
      responses:
        '200':
          description: Account deleted
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Hummingbird deleted.
        '401':
          description: Authentication Failed
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "Authentication Failed: invalid username and/or password." 
      tags:
        - Account management
  /api/addSong:
    post:
      description: Add a song at the platform
      parameters:
        - name: username
          in: header
          schema:
            type: string
          example: Hummingbird
        - name: password
          in: header
          schema:
            type: string
          example: passWord_1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                artist:
                  type: string
                tuning:
                  type: string
                capo:
                  type: string
                note:
                  type: string
                content:
                  type: string
            example:
              {
                "title":    "Fly Me to the Moon",
                "artist":   "Frank Sinatra",
                "tuning":   "E A D G B e",
                "capo":     "",
                "note":     "",
                "content":  "<lyrics with chords>"
              }
      responses:
        '200':
          description: Song successfully added
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song successfully added.
        '401':
          description: Authentication Failed
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "Authentication Failed: invalid username and/or password."
        '403':
          description: The song already exists
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: The song already exists.
      tags:
        - Song management
  /api/song/{artist}/{title}:
    put:
      description: Edit a song to the platform
      parameters:
        - name: artist
          in: path
          schema:
            type: string
          required: true
          example: Frank%20Sinatra
        - name: title
          in: path
          schema:
            type: string
          required: true
          example: Fly%20Me%20to%20the%20Moon
        - name: username
          in: header
          schema:
            type: string
          example: Hummingbird
        - name: password
          in: header
          schema:
            type: string
          example: passWord_1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tuning:
                  type: string
                capo:
                  type: string
                note:
                  type: string
                content:
                  type: string
            example:
              {
                "tuning":   "E A D G B e",
                "capo":     "",
                "note":     "",
                "content":  "<lyrics with chords>"
              }
      responses:
        '200':
          description: Song successfully edited
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song successfully edited.
        '401':
          description: Authentication Failed
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "Authentication Failed: invalid username and/or password." 
        '403':
          description: Permission denied
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "The user: Blackbird, does not have permission to edit the song."
        '404':
          description: Song not found
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song not found.
      tags:
        - Song management
    delete:
      description: Delete a song to the platform
      parameters:
        - name: artist
          in: path
          schema:
            type: string
          example: Frank%20Sinatra
          required: true
        - name: title
          in: path
          schema:
            type: string
          example: Fly%20Me%20to%20the%20Moon
          required: true
        - name: username
          in: header
          schema:
            type: string
          example: Hummingbird
        - name: password
          in: header
          schema:
            type: string
          example: passWord_1
      responses:
        '200':
          description: Song successfully deleted
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song successfully deleted.
        '401':
          description: Authentication Failed
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "Authentication Failed: invalid username and/or password."
        '403':
          description: Permission denied
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: "The user: Blackbird, does not have permission to edit the song."
        '404':
          description: Song not found
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song not found.
      tags:
        - Song management
    get:
      description: Get all the data of a specific song and extra data from theaudiodb.com
      parameters:
        - name: artist
          in: path
          schema:
            type: string
          example: Frank%20Sinatra
          required: true
        - name: title
          in: path
          schema:
            type: string
          example: Fly%20Me%20to%20the%20Moon
          required: true
      responses:
        '200':
          description: Song found, sent data about the song
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  artist:
                    type: string
                  tuning:
                    type: string
                  capo:
                    type: string
                  note:
                    type: string
                  content:
                    type: string
                  password:
                    type: string
                  owner:
                    type: string
                  album:
                    type: string
                  trackNo:
                    type: string
                  genre:
                    type: string
                  musicVid:
                    type: string
              example: 
                {
                  "title":    "Fly Me to the Moon",
                  "artist":   "Frank Sinatra",
                  "tuning":   "E A D G B e",
                  "capo":     "",
                  "note":     "",
                  "content":  "<lyrics with chords>",
                  "owner":    "Berna98k",
                  "album":    "Duets II",
                  "trackNo":  "6",
                  "genre":    "Swing",
                  "musicVid": null
                }
        '404':
          description: Song not found
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song not found.
      tags:
        - Get songs
  /api/songs:
    get:
      description: Get a list of all the songs on the platform
      responses:
        '200':
          description: DB is not empty, sent list of songs
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    artist:
                      type: string
              example:
                [
                  {
                    "title":  "All of Me",
                    "artist": "Frank Sinatra"
                  },
                  {
                    "title":  "All of Me",
                    "artist": "John Legend"
                  },
                  {
                    "title":  "Fly Me to the Moon",
                    "artist": "Frank Sinatra"
                  }
                ]
        '404':
          description: DB is empty, nothing to send
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Song not found.
      tags:
        - Get songs
  /api/songs/search:
    post:
      description: Get a filtered list of songs by artist or title (at most one of the two choices).
      parameters:
        - name: artist
          in: query
          schema:
            type: string
          example: Frank%20Sinatra
        - name: title
          in: query
          schema:
            type: string
          example: All%20of%20me
      responses:
        '200':
          description: Found songs by an artist, sent list of songs
          content:
            application/json; charset=utf-8:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    title:
                      type: string
                    artist:
                      type: string
              examples:
                'search by artist':
                  value: [
                    {
                      "title":  "All of Me",
                      "artist": "Frank Sinatra"
                    },
                    {
                      "title":  "Fly Me to the Moon",
                      "artist": "Frank Sinatra"
                    }
                  ]
                'search by title':
                  value: [
                    {
                      "title":  "All of Me",
                      "artist": "Frank Sinatra"
                    },
                    {
                      "title":  "All of Me",
                      "artist": "John Legend"
                    }
                  ]
        '404':
          description: Songs not found
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              example: Songs not found.
      tags:
        - Get songs
tags:
  - name: Account management
  - name: Song management
  - name: Get songs
externalDocs:
  description: GitHub
  url: https://github.com/alexbernardi360/guitar-composer