openapi.yaml

openapi: "3.0.2"

info:
  title: Godot Asset Library
  description: Godot Engine's asset library
  version: "1.0.0"
  termsOfService: https://github.com/godotengine/.github/blob/master/CODE_OF_CONDUCT.md
  contact:
    name: Contact the author
    url: https://github.com/fenix-hub
  license:
    name: MIT License
    url: https://github.com/godotengine/godot-asset-library/blob/master/LICENSE.txt

externalDocs:
  description: Markdown version
  url: https://github.com/fenix-hub/godot-asset-library/blob/swagger/API.md

servers:
  - url: "https://godotengine.org/asset-library/api"

tags:
  - name: assets
    description: Assets API

  - name: assetsEdit
    description: Assets Edit API

  - name: configure
    description: Configuration API

  - name: auth
    description: Authentication API

paths:
  /register:
    post:
      tags: [auth]
      summary: Register a user
      description: Register a user, given a username, password, and email.

      requestBody:
        description: Username, Password and Email to register
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDetails'

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/RegisterSuccessfulResult"

  /login:
    post:
      tags: [auth]
      summary: Login as a given user
      description: Login as a given user. Results in a token which can be used for authenticated requests.

      requestBody:
        description: Username and Passaword to login with
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsernamePassword'

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/LoginSuccessfulResult"
        '403':
          description: Forbidden
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/LoginForbiddenResult"
        '404':
          description: Not found
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/LoginNotFoundResult"

  /logout:
    post:
      tags: [auth]
      summary: Logout a user
      description: Logout a user, given a token. The token is invalidated in the process.

      requestBody:
        description: Username and Passaword to login with
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthToken"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/LogoutSuccessfulResult"

  /change_password:
    post:
      tags: [auth]
      summary: Change a user's password
      description: Change a user's password. The token is invalidated in the process.

      requestBody:
        description: Old and New password. The authentication token is mandatory.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangePassword'

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ChangePwdSuccessfulResult"

  /asset:
    get:
      tags: [assets]
      summary: List assets
      description: Return a paginated list of assets.

      parameters:
      - $ref: "#/components/parameters/typeParam"
      - $ref: "#/components/parameters/categoryParam"
      - $ref: "#/components/parameters/supportParam"
      - $ref: "#/components/parameters/filterParam"
      - $ref: "#/components/parameters/userParam"
      - $ref: "#/components/parameters/godotVersionParam"
      - $ref: "#/components/parameters/maxResultsParam"
      - $ref: "#/components/parameters/pageParam"
      - $ref: "#/components/parameters/offsetParam"
      - $ref: "#/components/parameters/sortParam"
      - $ref: "#/components/parameters/reverseParam"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/PaginatedAssetList"
              examples:
                PaginatedAssetListExample1:
                  $ref: "#/components/examples/PaginatedAssetListExample"

    post:
      tags: [assetsEdit]
      summary: Update information about an asset
      description: Update information about a single asset.

      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: "#/components/schemas/AuthToken"
              - $ref: "#/components/schemas/AssetDetails"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                type: object
                properties:
                  id:
                    description: The id of the updated asset
                    type: string


  /asset/{id}:
    get:
      tags: [assets]
      summary: Get information about an asset
      description: Get information about a single asset.

      parameters:
        - name: id
          in: path
          required: true
          description: The asset's unique identifier.
          schema:
            type: string

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/AssetDetails"
              examples:
                AssedDetailsExample1:
                  $ref: "#/components/examples/AssetDetailsExample"
        '404':
          description: Asset not found
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/AssetNotFound"
        '422':
          description: Invalid request body
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ValidationError"

    post:
      tags: [assetsEdit]
      summary: Update information about an asset
      description: Update information about a single asset.

      parameters:
        - name: id
          in: path
          required: true
          description: The asset's unique identifier.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AuthToken"
                - $ref: "#/components/schemas/AssetDetails"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                type: object
                properties:
                  id:
                    description: The id of the updated asset
                    type: string

  /asset/{id}/delete:
    post:
      tags: [assets]
      summary: Soft-delete an asset
      description: Soft-delete an asset. Usable by moderators and the owner of the asset.

      parameters:
        - name: id
          in: path
          required: true
          description: The asset's unique identifier.
          schema:
            type: string

      requestBody:
        description: The token for the authenticated user
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthToken"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/SuccessfulAssetOperation"

  /asset/{id}/support_level:
    post:
      tags: [assets]
      summary: Change the support level of an asset
      description: API used by moderators to change the support level of an asset.

      parameters:
        - name: id
          in: path
          required: true
          description: The asset's unique identifier.
          schema:
            type: string

      requestBody:
        description: The token for the authenticated user
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AuthToken"
                - type: object
                  properties:
                    token:
                      type: string
                    support_level:
                      type: string

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/SuccessfulAssetOperation"

  /asset/edit/{id}:
    get:
      tags: [assetsEdit]
      summary: Returns a previously-submitted asset edit
      description: Returns a previously-submitted asset edit. All fields with null are unchanged, and will stay the same as in the original. The previews array is merged from the new and original previews.

      parameters:
        - name: id
          in: path
          required: true
          description: The edit's unique identifier.
          schema:
            type: string

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/EditDetails"

    post:
      tags: [assetsEdit]
      summary: Update information about an asset
      description: Update information about a single asset.

      parameters:
        - name: id
          in: path
          required: true
          description: The asset's unique identifier.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AssetDetails"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                type: object
                properties:
                  id:
                    description: The id of the updated asset
                    type: string

  /asset/edit/{id}/review:
    post:
      tags: [assetsEdit]
      summary: Put an edit in review
      description: Moderator-only. Put an edit in review. It is impossible to change it after this.

      parameters:
        - name: id
          in: path
          required: true
          description: The edit's unique identifier.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthToken"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/EditSummary"

  /asset/edit/{id}/accept:
    post:
      tags: [assetsEdit]
      summary: Apply an edit previously put in review
      description: Moderator-only. Apply an edit previously put in review.

      parameters:
        - name: id
          in: path
          required: true
          description: The edit's unique identifier.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthToken"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/EditSummary"

  /asset/edit/{id}/reject:
    post:
      tags: [assetsEdit]
      summary: Reject an edit previously put in review
      description: Moderator-only. Reject an edit previously put in review.

      parameters:
        - name: id
          in: path
          required: true
          description: The edit's unique identifier.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AuthToken"
                - type: object
                  properties:
                    reason:
                      description: The reason why the edit was rejected
                      type: string

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/EditSummary"

  /configure:
    get:
      tags: [configure]
      summary: Fetch categories
      description: Returns category names and IDs (used for editor integration).

      parameters:
      - $ref: "#/components/parameters/typeParam"
      - $ref: "#/components/parameters/sessionParam"

      responses:
        '200':
          description: Successful operation
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Category"

        '422':
          description: Invalid request body
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ValidationError"

components:
  parameters:
    typeParam:
      in: query
      name: type
      required: false
      schema:
        type: string
        default: any
        enum:
          - any
          - addon
          - project
    categoryParam:
      in: query
      name: category
      required: false
      schema:
        type: string
    supportParam:
      in: query
      name: support
      required: false
      schema:
        type: string
        enum:
          - official
          - community
          - testing
    filterParam:
      in: query
      name: filter
      required: false
      schema:
        type: string
    userParam:
      in: query
      name: user
      required: false
      schema:
        type: string
    godotVersionParam:
      in: query
      name: godot_version
      required: false
      schema:
        type: string
        pattern: '^\d{1}.\d{1}.\d{1}$'
    maxResultsParam:
      in: query
      name: max_results
      required: false
      schema:
        type: string
        minimum: 1
        maximum: 500
    pageParam:
      in: query
      name: page
      required: false
      schema:
        type: string
    offsetParam:
      in: query
      name: offset
      required: false
      schema:
        type: string
    sortParam:
      in: query
      name: sort
      required: false
      schema:
        type: string
        enum:
          - rating
          - cost
          - name
          - updated
    reverseParam:
      in: query
      name: reverse
      required: false
      schema:
        type: boolean
    sessionParam:
      in: query
      name: session
      required: false
      schema:
        type: boolean


  schemas:
    AuthToken:
      type: object
      properties:
        token:
          type: string
      required:
        - token

    RegisterSuccessfulResult:
      type: object
      properties:
        registered:
          type: boolean
        username:
          type: string

    LoginSuccessfulResult:
      type: object
      properties:
        authenticated:
          type: boolean
        username:
          type: string
        token:
          type: string
        url:
          type: string

    LogoutSuccessfulResult:
      type: object
      properties:
        authenticated:
          type: boolean
        token:
          type: string

    ChangePwdSuccessfulResult:
      type: object
      properties:
        token:
          type: string

    LoginForbiddenResult:
      allOf:
      - $ref: "#/components/schemas/Error"
      - type: object
        properties:
          authenticated:
            type: boolean

    LoginNotFoundResult:
      allOf:
      - $ref: "#/components/schemas/Error"

    UsernamePassword:
      type: object
      properties:
        username:
          type: string
        password:
          type: string

    UserDetails:
      allOf:
      - $ref: "#/components/schemas/UsernamePassword"
      - type: object
        properties:
          email:
            type: string

    ChangePassword:
      type: object
      properties:
        token:
          type: string
        old_password:
          type: string
        new_password:
          type: string

    SuccessfulAssetOperation:
      type: object
      properties:
        changed:
          type: boolean

    EditSummary:
      type: object
      properties:
        edit_id:
          type: string
        status:
          type: string
        reason:
          type: string
        warning:
          type: string

    EditDetails:
      allOf:
        - $ref: "#/components/schemas/EditSummary"
        - $ref: "#/components/schemas/AssetSummary"
        - type: object
          properties:
            original:
              $ref: "#/components/schemas/AssetDetails"

    AssetSummary:
      type: object
      description: |
        A resource provided by the asset library (add-on, project, ...).
        These properties are returned both when requesting a list of assets or a specific asset.
      properties:
        token:
          type: string
          description: The Token obtained through a login.
        asset_id:
          type: string
          description: The asset's unique identifier.
        type:
          type: string
          description: The asset's type, can be "addon" or "project".
        author:
          type: string
          description: The author's username.
        author_id:
          type: string
          description: The author's unique identifier.
        category:
          type: string
          description: The category the asset belongs to.
        category_id:
          type: string
          description: The unique identifier of the category the asset belongs to.
        download_provider:
          type: string
          enum: [Custom, GitHub, GitLab, BitBucket, Gogs/Gitea, cgit]
          description: The download provider where the plugin source is hosted.
        download_commit:
          type: string
        download_hash:
          type: string
          default: ''
          description: >
            The asset's SHA-256 hash for the latest version.
            **Note:** This is currently always an empty string as asset versions' hashes aren't computed and stored yet.
        cost:
          type: string
          description: >
            The asset's license as a [SPDX license identifier](https://spdx.org/licenses/).
            For compatibility reasons, this field is called `cost` instead of `license`.
        godot_version:
          type: string
          description: >
            The Godot version the asset's latest version is intended for (in `major.minor` format).<br>
            This field is present for compatibility reasons with the Godot editor.
            See also the `versions` array.
        icon_url:
          type: string
          format: url
          description: The asset's icon URL (should always be a PNG image).
        is_archived:
          type: boolean
          description: >
            If `true`, the asset is marked as archived by its author.
            When archived, it can't receive any further reviews but can still be
            unarchived at any time by the author.
        issues_url:
          type: string
          format: url
          description: >
            The asset's issue reporting URL (typically associated with
            the Git repository specified in `browse_url`).
        modify_date:
          type: string
          format: date-time
          description: >
            The date on which the asset entry was last updated.
            Note that entries can be edited independently of new asset versions being released.
        rating:
          type: string
          description: >
            The asset's rating (unused). For compatibility reasons, a value of 0 is always returned.
            You most likely want `score` instead.
        support_level:
          type: string
          enum: [official, community, testing]
          description: The asset's support level.
        title:
          type: string
          description: The asset's title (usually less than 50 characters).
        version:
          type: string
          description: >
            The asset revision string (starting from 1).<br>
            Every time the asset is edited (for anyone and for any reason),
            this string is incremented by 1.
        version_string:
          type: string
          description: >
            The version string of the latest version (free-form, but usually `major.minor`
            or `major.minor.patch`).<br>
            This field is present for compatibility reasons with the Godot editor.
            See also the `versions` array.
        searchable:
          type: string
        previews:
          type: array
          items:
            $ref: "#/components/schemas/AssetPreview"

    PaginatedAssetList:
      description: A paginated list of assets.
      allOf:
        - $ref: "#/components/schemas/PaginationResult"
        - type: object
          properties:
            result:
              type: array
              items: { $ref: "#/components/schemas/AssetSummary" }

    AssetPreview:
      description: |
        ABCD.
      type: object
      properties:
        preview_id:
          type: string
        type:
          type: string
        link:
          type: string
          format: url
        thumbnail:
          type: string
          format: url

    AssetDetails:
      description: |
        A resource provided by the asset library (add-on, project, ...).<br>
        These properties are only returned when requesting a specific asset,
        not a list of assets.
      allOf:
        - $ref: "#/components/schemas/AssetSummary"
        - type: object
          properties:
            browse_url:
              type: string
              format: url
              description: The asset's browsable repository URL.
            description:
              type: string
              description: The asset's full description.
            download_url:
              type: string
              format: url
              description: >
                The download link of the asset's latest version (should always point to a ZIP archive).<br>
                This field is present for compatibility reasons with the Godot editor.
                See also the `versions` array.

    AssetVersion:
      type: object
      description: An asset version.
      properties:
        created_at:
          type: string
          format: date-time
          description: The version's release date.
        download_url:
          type: string
          format: url
          description: >
            The version's custom download URL (if any). Will be an empty string
            if not set.
        godot_version:
          type: string
          description: >
            The minor Godot version the asset version was declared to be
            compatible with (in `major.minor` format).
        version_string:
          type: string
          description: The version identifier.

    Category:
      type: object
      description: >
        A category in which assets belong to. An asset can only belong to
        one category at a time.
      properties:
        id:
          type: string
          description: The category's unique identifier.
        name:
          type: string
          description: The category's name.
        type:
          type: string
          description: The category's type (0 = Add-ons, 1 = Projects).

    PaginationResult:
      type: object
      description: Properties which describe the results of the pagination requested.
      properties:
        page:
          type: integer
          description: The requested page string.
        page_length:
          type: integer
          description: >
            The requested page length.<br>
            **Note:** This can be higher than the total amount of items returned.
        pages:
          type: integer
          description: >
            The total string of pages available.<br>
            **Note:** If requesting a page higher than this value, a successful
            response will be returned (status code 200) but no items will be listed.
        total_items:
          type: integer
          description: The total string of items available.

    AssetNotFound:
      allOf:
      - $ref: "#/components/schemas/Error"

    Error:
      type: object
      description: The requested resource was not found.
      properties:
        error:
          type: string
          description: A generic error message.

    TraceError:
      type: object
      properties:
        file:
          type: string
        line:
          type: string
        function:
          type: string
        class:
          type: string
        type:
          type: string

    ValidationError:
      type: object
      description: An error returned by Laravel.
      properties:
        errors:
          type: array
          items:
            type: string
            description: Messages describing why the validation of the field failed.
        message:
          type: string
          description: A generic error message.

  examples:
    AssetDetailsExample:
      value:
        asset_id: '1'
        type: addon
        title: Snake
        author: test
        author_id: '1'
        version: '1'
        version_string: alpha
        category: 2D Tools
        category_id: '1'
        godot_version: '2.1'
        rating: '0'
        cost: GPLv3
        description: Lorem ipsum…
        support_level: testing
        download_provider: GitHub
        download_commit: master
        download_hash: "(sha256 hash of the downloaded zip)"
        browse_url: https://github.com/…
        issues_url: https://github.com/…/issues
        icon_url: https://….png
        searchable: '1'
        modify_date: '2018-08-21 15:49:00'
        download_url: https://github.com/…/archive/master.zip
        previews:
        - preview_id: '1'
          type: video
          link: https://www.youtube.com/watch?v=…
          thumbnail: https://img.youtube.com/vi/…/default.jpg
        - preview_id: '2'
          type: image
          link: https://….png
          thumbnail: https://….png

    PaginatedAssetListExample:
      value:
        result:
        - asset_id: '1'
          title: Snake
          author: test
          author_id: '1'
          category: 2D Tools
          category_id: '1'
          godot_version: '2.1'
          rating: '0'
          cost: GPLv3
          support_level: testing
          icon_url: https://….png
          version: '1'
          version_string: alpha
          modify_date: '2018-08-21 15:49:00'
        page: 0
        pages: 0
        page_length: 10
        total_items: 1