simple-comment-api.json

{
  "openapi": "3.0.2",
  "info": {
    "title": "Simple Comment API",
    "description": "A REST OpenAPI 3.0 Comment API",
    "contact": {
      "name": "Rendall Koski",
      "url": "https://github.com/rendall/simple-comment/issues"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/comment-api/v1"
    }
  ],
  "security": [
    {},
    {
      "BasicAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/topic": {
      "get": {
        "summary": "Discussion discovery",
        "description": "Receive a listing of all discussions",
        "responses": {
          "200": {
            "description": "List available discussions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Discussion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to view topics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      },
      "post": {
        "summary": "Create a new topic",
        "responses": {
          "201": {
            "description": "Topic created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Topic"
                }
              }
            }
          },
          "400": {
            "description": "Request format not understood",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to create topics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too much discussion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/topic/{topicId}": {
      "get": {
        "summary": "View topic and its comments",
        "parameters": [
          {
            "name": "topicId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List comments for {topicId}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discussion"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to view discussion {topicId}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "{commentId} is not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      },
      "put": {
        "summary": "Edit a topic",
        "parameters": [
          {
            "name": "topicId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Topic {topicId} updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to update this comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Topic {topicId} not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "delete": {
        "summary": "Delete a discussion",
        "parameters": [
          {
            "name": "topicId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Discussion of topic {topicId} deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to delete this comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/comment/{commentId}": {
      "post": {
        "summary": "Reply to comment or topic {commentId}",
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/text"
        },
        "responses": {
          "201": {
            "description": "Comment created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comment"
                }
              }
            }
          },
          "400": {
            "description": "Request format not understood",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to post this comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Comment is too long",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "425": {
            "description": "Possible duplicate comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many comments",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "get": {
        "summary": "View specific comment and its descendants",
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List comments for {commentId}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Discussion"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to view discussion {commentId}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "{commentId} is not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      },
      "put": {
        "summary": "Edit a comment",
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/text"
        },
        "responses": {
          "204": {
            "description": "Comment {commentId} updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to update this comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Comment {commentId} not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "delete": {
        "summary": "Delete a comment",
        "parameters": [
          {
            "name": "commentId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Comment {commentId} deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to delete this comment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/user": {
      "get": {
        "summary": "List all users",
        "responses": {
          "200": {
            "description": "List users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/User"
                  }
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to view users",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      },
      "post": {
        "summary": "Create a user",
        "description": "Creates an authenticated user who can log in over mutliple devices. If the authId is a temporary user, link the temporary user to the authenticated user",
        "responses": {
          "201": {
            "description": "User created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "400": {
            "description": "Request format not understood",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Requesting user is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Requesting user is not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "UserId exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/user/{userId}": {
      "get": {
        "summary": "View a user",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "View user {userId}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to view this user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User {userId} not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {},
          {
            "BearerAuth": []
          }
        ]
      },
      "put": {
        "summary": "Edit a user",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "User {userId} updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to update this user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User {userId} not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "delete": {
        "summary": "Delete a user",
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string",
              "format": "byte"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "User deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "User is not authorized to delete this user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "User {userId} not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/auth": {
      "get": {
        "summary": "Accept a user name and password, return authentication token",
        "description": "The authentication token is set via the Set-Cookie header with a 'simple_comment_token' key or as an Authentication header with Bearer scheme, depending on Simple Comment configuration. If the authId is a temporary user, link the temporary user to the authenticated user",
        "responses": {
          "200": {
            "description": "User authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthToken"
                }
              }
            }
          },
          "400": {
            "description": "Request format not understood",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bad credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BasicAuth": []
          }
        ]
      },
      "post": {
        "summary": "Accept a user name and password, return authentication token",
        "description": "The authentication token is set via the Set-Cookie header with a 'simple_comment_token' key or as an Authentication header with Bearer scheme, depending on Simple Comment configuration. If the authId is a temporary user, link the temporary user to the authenticated user",
        "responses": {
          "200": {
            "description": "User authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthToken"
                }
              }
            }
          },
          "400": {
            "description": "Request format not understood",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Bad credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BasicAuth": []
          }
        ]
      },
      "delete": {
        "summary": "Revoke authentication / log out",
        "description": "Sets the Cookie token to expire in the past or the revokes the Authentication header",
        "responses": {
          "202": {
            "description": "Authentication revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          }
        }
      }
    },
    "/gauth": {
      "get": {
        "summary": "Receive tempororary or non-authenticated credentials",
        "description": "The authentication token is set via Authentication header with Bearer scheme, expected to be set as a cookie in the user's browser and used until an authenticated user is created. The activity of the temporary user should be linked to the authenticated user if possible",
        "responses": {
          "200": {
            "description": "User authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthToken"
                }
              }
            }
          },
          "429": {
            "description": "Too many hits on this endpoint in a short amount of time",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/verify": {
      "get": {
        "summary": "Return a representation of a claim in the Cookie header 'simple-comment-token' value",
        "responses": {
          "200": {
            "description": "User authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Token is corrupted"
          },
          "401": {
            "description": "User is not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Token is expired"
          }
        },
        "security": [
          {
            "BasicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Success": {
        "required": ["statusCode", "body"],
        "type": "object",
        "properties": {
          "body": {
            "type": "string"
          },
          "statusCode": {
            "maximum": 299,
            "minimum": 200,
            "type": "integer"
          }
        },
        "description": "Success message when no other information is expected"
      },
      "Error": {
        "required": ["statusCode", "body"],
        "type": "object",
        "properties": {
          "body": {
            "type": "string"
          },
          "statusCode": {
            "maximum": 499,
            "minimum": 400,
            "type": "integer"
          }
        },
        "description": "Error message "
      },
      "Comment": {
        "required": ["id", "userId", "text", "parentId", "dateCreated"],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "byte"
          },
          "userId": {
            "type": "string",
            "format": "byte"
          },
          "user": {
            "$ref": "#/components/schemas/User"
          },
          "text": {
            "type": "string"
          },
          "parentId": {
            "type": "string",
            "format": "byte"
          },
          "replies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comment"
            }
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time"
          },
          "dateDeleted": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "User": {
        "type": "object",
        "required": ["id", "name"],
        "properties": {
          "id": {
            "type": "string",
            "format": "byte"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "hash": {
            "type": "string"
          },
          "isAdmin": {
            "type": "boolean",
            "description": "true if the user is admin, false otherwise"
          },
          "isVerified": {
            "type": "boolean"
          }
        }
      },
      "AuthToken": {
        "type": "string"
      },
      "Topic": {
        "type": "object",
        "required": ["id", "title", "isLocked", "dateCreated"],
        "properties": {
          "id": {
            "type": "string",
            "format": "byte"
          },
          "title": {
            "type": "string"
          },
          "isLocked": {
            "type": "boolean"
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Discussion": {
        "type": "object",
        "required": ["id", "title", "isLocked", "dateCreated"],
        "properties": {
          "id": {
            "type": "string",
            "format": "byte"
          },
          "title": {
            "type": "string"
          },
          "isLocked": {
            "type": "boolean"
          },
          "replies": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comment"
            }
          },
          "dateCreated": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "parameters": {
      "userId": {
        "name": "userId",
        "in": "path",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string",
          "format": "byte"
        }
      },
      "topicId": {
        "name": "topicId",
        "in": "path",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string",
          "format": "byte"
        }
      },
      "commentId": {
        "name": "commentId",
        "in": "path",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string",
          "format": "byte"
        }
      },
      "authToken": {
        "name": "authToken",
        "in": "header",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "type": "string",
          "format": "byte"
        }
      }
    },
    "requestBodies": {
      "text": {
        "description": "This is the body copy of the reply to a topic or comment",
        "content": {
          "text/plain": {
            "schema": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "description": "'BasicAuth' returns an 'BearerAuth' bearer token",
        "scheme": "basic"
      },
      "BearerAuth": {
        "type": "http",
        "description": "All API requests that require authentication shall be 'BearerAuth'",
        "scheme": "bearer",
        "bearerFormat": "JWT with 'user' field"
      }
    }
  }
}