Rebase API OpenAPI Spec

rebase-openapi3.yml

# Copyright(C) 2018 duangsuse
# A RESTful API for everyone. Open Source.
# Licensed under CC-BY

# Fit OpenAPI 3.0.0 standards
openapi: 3.0.0

# Added by API Auto Mocking Plugin
# Testing servcices
servers:
  - description: Drakeet.me offical service
    url: https://api.drakeet.com/rebase
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/duangsuse/RebaseApi/0.7.2
  - description: RebaseD offical service
    url: https://rebase-api.popf.rip/

# External docs
externalDocs:
  description: RebaseD Project API document, markdown version
  url: https://github.com/duangsuse/RebaseD/blob/master/rebase-api.md

# API Document informations
info:
  # Version of this API
  version: '0.7.2'
  # True open source
  title: Microblogging open API for everyone
  description: |
    ## Basics
    A __RESTful API__ for everyone. Open Source at [duangsuse/RebaseD](https://github.com/duangsuse/RebaseD)
    All API access is over __HTTPS__. All data is sent and received as __JSON__.
    ```yaml
    Content-Type: application/json; charset=utf-8
    ```
    All timestamps are returned in __ISO 8601__ format
    ```plain
    YYYY-MM-DDTHH:MM:SSZ
    ```

    ## Author
    This describes the resources that make up the official Rebase API by [drakeet](https://github.com/drakeet).

    If you have any problems or requests please contact [drakeet](https://github.com/drakeet) or create an issue.

    ## Params
    Many APIs take optional parameters. For __GET__ requests, any parameters not specified as a __segment in the path__ can be passed as an __HTTP query string__ parameter:

    ```javascript
    GET https://api.drakeet.com/rebase/categories/drakeet/fun/feeds?size=15&last_id=123
    ```

    For __POST, PATCH, PUT, and DELETE__ requests, parameters __not included in the URL__ should be __encoded as JSON__ with a `Content-Type` of `application/json`.

    ## Access Tokens

    Access token is required for all __POST, PATCH, PUT, and DELETE__ requests, except for __user registering__.

    Header

    ```yml
    Authorization: token YOUR-TOKEN
    ```

    ## Client Errors

    There is only one type of errors on API calls.

    Status __4xx__ Description

    ```json
    {
      "error": "Not Found"
    }
    ```


  # Contact duangsuse
  contact:
    name: duangsuse
    email: [email protected]
    url: https://github.com/duangsuse

  # Licensed under Apache 2.0
  license:
    name: 'OpenAPI 3 Specification Licensed under Apache 2.0'
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

# API Tags
tags:
  - name: Misc
    description: miscellaneous interfaces
  - name: User
    description: rebase user operations
  - name: Category
    description: blogging categories
  - name: Feed
    description: microblogging post operations

# API Request methods
paths:
  /:
    get:
      tags:
        - Misc
      summary: Get Rebase API OpenAPI v3.0.0 index
      operationId: getOpenAPI
      responses:
        200:
          description: Got JSON API Tree response
          content:
            application/json:
              schema:
                type: object
                description: Fields omitted
        404:
          description: Not supported by server
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /markdown:
    post:
      tags:
        - Misc
      summary: Render a markdown document to HTML
      operationId: renderMarkdown
      requestBody:
        $ref: '#/components/requestBodies/MarkdownRender'
      responses:
        200:
          description: Markdown rendered as HTML
          content:
            application/json:
              schema:
                type: object
                properties:
                  rendered:
                    type: string
                    format: html
                    nullable: false
                    example: <h1>Hello</h1>
        422:
          description: Render failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Server not support markdown render
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /version:
    get:
      tags:
        - Misc
      summary: Get server and API version
      operationId: getVersion
      responses:
        200:
          description: Got versions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiVersion'
        404:
          description: Not supported by server
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /datastorage:
    get:
      tags:
        - Misc
      summary: Internal API to get server public datastorage
      operationId: internalGetStorage
      responses:
        200:
          description: Got datastorage
          content:
            application/json:
              schema:
                type: object
                description: fields omitted
        404:
          description: Not supported by server
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users:
    post:
      tags:
        - User
      requestBody:
        $ref: '#/components/requestBodies/User'
      summary: Create a rebase user
      operationId: createUser
      responses:
        201:
          description: Created
          headers:
            Location:
              description: New user location
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /authorizations/{username}:
    get:
      tags:
        - User
      summary: Authorize user
      operationId: getToken
      parameters:
        - name: password
          in: query
          description: user password
          required: true
          schema:
            type: string
            example: sa1tedFi$h
        - name: username
          in: path
          description: user to login
          schema:
            type: string
            example: drakeet
          required: true
      responses:
        200:
          description: Got app token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        default:
          description: Auth failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /categories/{owner}:
    get:
      tags:
        - Category
      summary: List categories of someone
      operationId: listCategoriesOf
      parameters:
        - name: owner
          in: path
          description: owned user
          schema:
            type: string
            example: rachel
          required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        default:
          description: Query failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      tags:
        - Category
      summary: Create a category
      operationId: createCategory
      parameters:
        - name: owner
          in: path
          description: owned user
          schema:
            type: string
          required: true
      requestBody:
        $ref: '#/components/requestBodies/Category'
      responses:
        201:
          description: Created
          headers:
            Location:
              description: New category location
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        default:
          description: Creation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /categories/{owner}/{category}/feeds:
    get:
      tags:
        - Feed
      summary: List feeds in a category
      operationId: getFeeds
      parameters:
        - name: last_id
          in: query
          description: the last feed id of the feeds
          allowEmptyValue: true
          schema:
            type: string
            default: ''
            example: '3'
          required: false
        - name: size
          in: query
          description: the size of the feeds, number, default 20
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 20
          required: false
          allowEmptyValue: false
        - name: owner
          in: path
          description: Owner
          schema:
            type: string
          required: true
        - name: category
          in: path
          description: Category
          schema:
            type: string
          required: true
      responses:
        200:
          description: Query OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      tags:
        - Feed
      summary: Create a feed
      operationId: createFeed
      requestBody:
        $ref: '#/components/requestBodies/Feed'
      parameters:
        - name: owner
          in: path
          description: Owner
          schema:
            type: string
            example: duangsuse
          required: true
        - name: category
          in: path
          description: Category
          schema:
            type: string
            example: 生活
          required: true
      responses:
        201:
          description: Created
          headers:
            Location:
              description: New feed location
              schema:
                type: string
                format: url
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        default:
          description: Feed creation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /categories/{owner}/{category}/feeds/{_id}:
    patch:
      tags:
        - Feed
      summary: Edit a feed
      operationId: updateFeed
      parameters:
        - name: owner
          in: path
          description: Owner
          schema:
            type: string
            example: rikka
          required: true
        - name: category
          in: path
          description: Category
          schema:
            type: string
            example: dev
          required: true
        - name: _id
          in: path
          description: ID
          schema:
            type: string
            format: integer
            example: '1'
          required: true
      requestBody:
        $ref: '#/components/requestBodies/FeedUpdate'
      responses:
        200:
          description: OK, changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
        default:
          description: Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Feed
      summary: Delete a feed
      operationId: deleteFeed
      parameters:
        - name: owner
          in: path
          description: Owner
          schema:
            type: string
          required: true
        - name: category
          in: path
          description: Category
          schema:
            type: string
          required: true
        - name: _id
          in: path
          description: ID
          schema:
            type: string
          required: true
      responses:
        204:
          description: Deleted
        default:
          description: Failed to delete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

# Rebase Model data
components:
  schemas:
    Error:
      description: Request error description
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: error message
          example: Failed to open database connection
          nullable: true

    # Rebase user model
    User:
      description: A rebase user can have name, password, email, etc.
      type: object
      properties:
        username:
          type: string
          format: simplename
          example: fish
        password:
          type: string
          example: sa1tedFi$h
        name:
          type: string
          example: Fish
        email:
          type: string
          format: email
        description:
          type: string
          example: 咸鱼
        created_at:
          type: string
          format: date-time
        authorization:
          $ref: '#/components/schemas/AuthToken'

    # Blogging category
    Category:
      description: A user can create up to 11 categories, only owner can change categories
      type: object
      properties:
        key:
          type: string
          example: main
        name:
          type: string
          example: 主文件夹
        rank:
          type: integer
          format: int32
          minimum: 0
        owner:
          type: string

    # Microblogging post
    Feed:
      description: By default, all the UGCs are public, but only the owner can publish or change (owned) feeds.
      type: object
      required:
        - title
      properties:
        title:
          type: string
          example: 下雨了，一起来写小文章吧
        content:
          type: string
          example: 就这么写吧 QWQ
        url:
          type: string
          format: url
        cover_url:
          type: string
          format: url
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
        owner:
          type: string
          example: drakeet
        category:
          type: string
          example: 随笔
        _id:
          type: string

    # Auth token result
    AuthToken:
      description: Authorization token
      type: object
      required:
        - access_token
        - updated_at
      properties:
        access_token:
          type: string
          example: '01234567'
        updated_at:
          type: string
          format: date-time

    # API Version
    ApiVersion:
      description: Rebase API Version
      type: object
      required:
        - version
      properties:
        version:
          type: string
          format: semver
          nullable: false
        server:
          type: string
        server-version:
          type: string

# POST Request bodies
  requestBodies:
    # Markdown render
    MarkdownRender:
      description: Markdown text to render to HTML
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - literal
            properties:
              literal:
                type: string
                format: markdown
                example: '# Hello'
                nullable: false

    # Rebase API user
    User:
      description: Create new user
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [username, password, name, email, description]
            properties:
              username:
                type: string
                example: wang_tiezhu
              password:
                type: string
                example: '1234567'
              name:
                type: string
                example: 王铁柱
              email:
                type: string
                format: email
              description:
                type: string
                example: 理工科文艺青年一枚 0_0

    # Blogging category
    Category:
      description: Create new category
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - key
              - name
            properties:
              key:
                type: string
                example: cat
              name:
                type: string
                example: 猫猫
              rank:
                type: integer
                format: int32
                minimum: 0

    # Microblogging post
    Feed:
      description: Create new feed
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - title
            properties:
              title:
                type: string
                example: 一起来写小文章吧！
              content:
                type: string
                example: 我们就这么写\n哈哈哈
              url:
                type: string
                format: url
              cover_url:
                type: string
                format: url

    # Microblogging post update
    FeedUpdate:
      description: Update feed
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              title:
                type: string
                example: 一起来写小文章吧！
              content:
                type: string
                example: 我们就这么写\n哈哈哈
              url:
                type: string
                format: url
              cover_url:
                type: string
                format: url
              category:
                type: string
                example: 文章

  # Rebase API token auth
  securitySchemes:
    AuthorizationHeaderToken:
      type: apiKey
      name: Authorization
      in: header
      description: should be started with token <spacer> sequence