swagger.yml

swagger: '2.0'
info:
  version: '2.0'
  title: Spiget
  license:
    name: Apache License 2.0
    url: 'https://github.com/SpiGetOrg/Spiget/blob/master/LICENSE.md'
  contact:
    name: inventivetalent
    url: 'https://inventivetalent.org/contact'
    email: info@inventivetalent.org
  description: |
    Documentation for Spiget
    Spiget is an API to quickly and easily get information about Spigot plugins, resources and authors
schemes:
  - https
  - http
host: api.spiget.org
basePath: /v2
produces:
  - application/json
consumes:
  - application/json
paths:
  /status:
    get:
      tags:
        - status
      summary: API Status
      description: |
        Get the API status
      responses:
        '200':
          description: OK
          schema:
            properties:
              status:
                description: Status overview
                type: object
                properties:
                  fetch:
                    type: object
                    properties:
                      start:
                        description: Timestamp of the last fetcher start
                        type: number
                        format: long
                      end:
                        description: Timestamp of the last fetcher end (0 if currently active)
                        type: number
                        format: long
                      active:
                        description: Whether the fetcher is currently active
                        type: boolean
                      page:
                        type: object
                        properties:
                          amount:
                            description: Amount of pages to load
                            type: number
                            format: integer
                          index:
                            description: Current page index
                            type: number
                            format: integer
                          item:
                            type: object
                            properties:
                              index:
                                description: Resource index on the current page
                                type: number
                                format: integer
              stats:
                description: API stats
                type: object
                properties:
                  resources:
                    description: Resource count
                    type: number
                    format: integer
                  authors:
                    description: Author count
                    type: number
                    format: integer
                  categories:
                    description: Category count
                    type: number
                    format: integer
                  resource_updates:
                    description: Resource update count
                    type: number
                    format: integer
                  resource_versions:
                    description: Resource version count
                    type: number
                    format: integer
  /resources:
    get:
      tags:
        - resources
      summary: Resource List
      description: |
        Get a list of available resources (premium and free)
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  /resources/premium:
    get:
      tags:
        - resources
      summary: Premium Resource List
      description: |
        Get a list of available premium resources
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  /resources/free:
    get:
      tags:
        - resources
      summary: Free Resource List
      description: |
        Get a list of available free resources
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  '/resources/{resource}':
    get:
      tags:
        - resources
      summary: Resource Details
      description: |
        Get a resource by its ID
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Resource'
        '404':
          $ref: '#/responses/notFound'
  '/resources/{resource}/author':
    get:
      tags:
        - resources
      summary: Resource Author
      description: |
        Get the resource author
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Author'
  '/resources/{resource}/download':
    get:
      tags:
        - resources
      summary: Resource Download
      description: |
        Download a resource
        This either redirects to spiget's CDN server (cdn.spiget.org) for a direct download of files hosted on spigotmc.org or to the URL of externally hosted resources
        The `external` field of a resource should be checked before downloading, to not receive any unexpected data
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
      responses:
        '302':
          description: |
            File found
            Redirect to the file direct download OR the url of externally hosted resources
          headers:
            X-Spiget-File-Source:
              type: string
              description: File source, either `cdn` or `external`
        '404':
          description: Resource not found / File not Found
  '/resources/{resource}/versions':
    get:
      tags:
        - resources
      summary: Resource Versions
      description: |
        Get versions of a resource
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/versionArray'
  '/resources/{resource}/versions/{version}':
    get:
      tags:
        - resources
      summary: Resource Version
      description: |
        Get a specific resource version by its ID
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - name: version
          type: number
          description: Version ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ResourceVersion'
        '404':
          $ref: '#/responses/notFound'
  '/resources/{resource}/versions/latest':
    get:
      tags:
        - resources
      summary: Latest Resource Version
      description: |
        Get the latest resource version
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ResourceVersion'
        '404':
          $ref: '#/responses/notFound'
  '/resources/{resource}/versions/{version}/download':
    get:
      tags:
        - resources
      summary: Resource Version Download
      description: |
        Download a specific resource version

        Note: This only redirects to the stored download location and might not download a file
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - name: version
          type: string
          description: Version ID or 'latest'
          in: path
          required: true
      responses:
        '302':
          description: Redirect to the download location
          headers:
            Location:
              description: Download location
              type: string
  '/resources/{resource}/versions/{version}/download/proxy':
    get:
      tags:
        - resources
      summary: Resource Version Proxy Download
      description: |
        Download a specific resource version
        Attempts to proxy a version download from spigotmc.org
        Note: this endpoint has a pretty strict rate-limit - cache downloaded versions locally and avoid repeated requests.
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - name: version
          type: string
          description: Version ID or 'latest'
          in: path
          required: true
      responses:
        '302':
          description: Version download
  '/resources/{resource}/updates':
    get:
      tags:
        - resources
      summary: Resource Updates
      description: |
        Get updates of a resource
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/updateArray'
  '/resources/{resource}/updates/latest':
    get:
      tags:
        - resources
      summary: Latest Resource Update
      description: |
        Get the latest resource update
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/ResourceUpdate'
        '404':
          $ref: '#/responses/notFound'
  '/resources/{resource}/reviews':
    get:
      tags:
        - resources
      summary: Resource Reviews
      description: |
        Get reviews of a resource
      parameters:
        - name: resource
          type: number
          description: Resource ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/reviewArray'
  /resources/new:
    get:
      tags:
        - resources
      summary: New Resources
      description: |
        Get all new resources
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  '/resources/for/{version}':
    get:
      tags:
        - resources
      summary: Resources for Versions
      description: |
        Get resources for the specified version(s)
      parameters:
        - name: version
          type: string
          description: 'Version(s), separated by commas'
          in: path
          required: true
        - name: method
          type: string
          enum:
            - any
            - all
          description: Method to use to check for versions
          in: query
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  /authors:
    get:
      tags:
        - authors
      summary: Author List
      description: |
        Get a list of available authors
        Note: This only includes members involved with resources, either being their author or having reviewed a resource
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/authorArray'
  '/authors/{author}':
    get:
      tags:
        - authors
      summary: Author Details
      description: |
        Get details about an author
      parameters:
        - name: author
          type: number
          description: Author ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Author'
  '/authors/{author}/resources':
    get:
      tags:
        - authors
      summary: Author resources
      description: |
        Get an author's resources
      parameters:
        - name: author
          type: number
          description: Author ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  '/authors/{author}/reviews':
    get:
      tags:
        - authors
      summary: Author reviews
      description: |
        Get an author's reviews left on resources
      parameters:
        - name: author
          type: number
          description: Author ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/reviewArray'
  /categories:
    get:
      tags:
        - categories
      summary: Category List
      description: |
        Get a list of categories
      parameters:
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/categoryArray'
  '/categories/{category}':
    get:
      tags:
        - categories
      summary: Category Details
      description: |
        Get details about a category
      parameters:
        - name: category
          type: number
          description: Category ID
          in: path
          required: true
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Category'
  '/categories/{category}/resources':
    get:
      tags:
        - categories
      summary: Category Resources
      description: |
        Get the resources in a category
      parameters:
        - name: category
          type: number
          description: Category ID
          in: path
          required: true
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  '/search/resources/{query}':
    get:
      tags:
        - search
        - resources
      summary: Resource Search
      description: |
        Search resources
      parameters:
        - name: query
          type: string
          description: Search query
          in: path
          required: true
        - name: field
          type: string
          description: Field to search in
          in: query
          enum:
            - name
            - tag
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/resourceArray'
  '/search/authors/{query}':
    get:
      tags:
        - search
        - authors
      summary: Author Search
      description: |
        Search authors
      parameters:
        - name: query
          type: string
          description: Search query
          in: path
          required: true
        - name: field
          type: string
          description: Field to search in
          in: query
          enum:
            - name
        - $ref: '#/parameters/sizeParam'
        - $ref: '#/parameters/pageParam'
        - $ref: '#/parameters/sortParam'
        - $ref: '#/parameters/fieldsParam'
      responses:
        '200':
          $ref: '#/responses/authorArray'
  /webhook/events:
    get:
      tags:
        - webhook
      summary: Webhook events
      description: |
        Get a list of available events
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              events:
                description: Events
                type: array
                items:
                  type: string
  /webhook/register:
    post:
      tags:
        - webhook
      summary: Register Webhook
      description: |
        Register a new Webhook

        Use this form to easily register a new one: https://spiget.org/webhook/
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: url
          type: string
          description: URL to call
          in: formData
          required: true
        - name: events
          type: array
          description: Events to register
          items:
            type: string
          in: formData
          required: true
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              id:
                type: string
                description: ID of the registered Webhook
              secret:
                type: string
                description: Registration secret
        '400':
          description: Invalid request
          schema:
            type: object
            properties:
              error:
                type: string
                description: Error message
  '/webhook/status/{id}':
    get:
      tags:
        - webhook
      summary: Webhook Status
      description: |
        Get the status of a Webhook
      parameters:
        - name: id
          in: path
          type: string
          description: ID of the Webhook
          required: true
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              status:
                type: number
                format: integer
                description: Status id
              failedConnections:
                type: number
                format: integer
                description: Amount of failed connections
  '/webhook/delete/{id}/{secret}':
    delete:
      tags:
        - webhook
      summary: Delete Webhook
      description: |
        Delete a Webhook
      parameters:
        - name: id
          in: path
          type: string
          description: Webhook ID
          required: true
        - name: secret
          in: path
          type: string
          description: Webhook Secret
          required: true
      responses:
        '200':
          description: OK
        '404':
          $ref: '#/responses/notFound'
definitions:
  Resource:
    title: Resource
    type: object
    description: Main Resource model.
    properties:
      id:
        type: number
        format: integer
        description: Id of the Resource.
      name:
        type: string
        description: Name of the Resource.
      tag:
        type: string
        description: Tag line of the Resource.
      contributors:
        type: string
        description: Contributors of the Resource.
      likes:
        type: number
        format: integer
        description: Number of likes.
      file:
        $ref: '#/definitions/ResourceFile'
      testedVersions:
        type: array
        description: List with Tested Versions of the Resource.
        items:
          type: string
      links:
        type: object
        description: Map of external and custom links in the resource description.
      rating:
        $ref: '#/definitions/ResourceRating'
      releaseDate:
        type: number
        format: long
        description: Release timestamp.
      updateDate:
        type: number
        format: long
        description: Update timestamp.
      downloads:
        type: number
        format: integer
        description: Amount of downloads.
      external:
        type: boolean
        description: Whether this resource is external (not hosted on SpigotMC.org).
      icon:
        $ref: '#/definitions/Icon'
      premium:
        type: boolean
        description: Whether the resource is a premium resource.
      price:
        type: number
        format: double
        description: Price of the resource (only if the resource is premium).
      currency:
        type: string
        description: Price Currency of the resource (only if the resource is premium).
      author:
        $ref: '#/definitions/IdReference'
      category:
        $ref: '#/definitions/IdReference'
      version:
        $ref: '#/definitions/IdAndUUIDReference'
      reviews:
        description: List of review IDs on this resource - only present if directly requesting the resource.
        type: array
        items:
          $ref: '#/definitions/IdReference'
      versions:
        description: List of version IDs of this resource - only present if directly requesting the resource.
        type: array
        items:
          $ref: '#/definitions/IdReference'
      updates:
        description: List of update IDs of this resource - only present if directly requesting the resource.
        type: array
        items:
          $ref: '#/definitions/IdReference'
      description:
        description: Base64-encoded description HTML.
      documentation:
        description: Base64-encoded documentation HTML (from the Documentation tab).
      sourceCodeLink:
        type: string
        description: Source Code link of the Resource.
      donationLink:
        type: string
        description: Donation link of the Resource.
  ResourceFile:
    title: Resource File
    description: Model of a Resource File.
    type: object
    properties:
      type:
        type: string
        description: 'File extension (.jar, .zip, .sk) or "external".'
      size:
        type: number
        format: float
        description: File size.
      sizeUnit:
        type: string
        description: 'File size-unit (KB, MB, GB).'
      url:
        type: string
        description: Relative URL to the file.
      externalUrl:
        type: string
        description: URL of external downloads.
  Icon:
    title: Resource Icon / Author Avatar
    description: Model for Recource Icon or Author Avatar.
    type: object
    properties:
      url:
        type: string
        description: Relative URL to the image.
      data:
        type: string
        description: Base64-Encoded image data.
  ResourceVersion:
    title: Resource Version
    description: Model for a Resource Version.
    type: object
    properties:
      id:
        type: number
        format: integer
        description: Version ID.
        deprecated: true
      uuid:
        type: string
        description: Version UUID.
      name:
        type: string
        description: Version name (e.g. v1.0).
      releaseDate:
        type: number
        format: long
        description: Timestamp of the version's release date.
      downloads:
        type: number
        format: integer
        description: Amount of downloads.
      rating:
        $ref: '#/definitions/ResourceRating'
  ResourceUpdate:
    title: Resource Update
    description: Model for a Resource Update.
    type: object
    properties:
      id:
        type: number
        format: integer
        description: Update ID.
      resource:
        type: number
        format: integer
        description: Resource ID.
      title:
        type: string
        description: Update title.
      description:
        type: string
        description: Base64-Encoded description of the update.
      date:
        type: number
        format: long
        description: Update timestamp.
      likes:
        type: number
        format: integer
        description: Amount of likes for this update.
  ResourceRating:
    title: Resource Rating
    description: Model for a Resource Rating.
    type: object
    properties:
      count:
        type: number
        format: integer
        description: Number of ratings.
      average:
        type: number
        format: float
        description: Average rating.
  ResourceReview:
    title: Resource Review
    description: Model for a Resource Review.
    type: object
    properties:
      author:
        $ref: '#/definitions/Author'
      rating:
        $ref: '#/definitions/ResourceRating'
      message:
        type: string
        description: Base64-Encoded Review message.
      responseMessage:
        type: string
        description: Base64-Encoded message the author responded with.
      version:
        type: string
        description: Version name the review was posted for.
      date:
        type: number
        format: long
        description: Review timestamp.
  Author:
    title: Author
    description: Model for an Author.
    type: object
    properties:
      id:
        type: number
        format: integer
        description: Id of the author.
      name:
        type: string
        description: Author name.
      icon:
        $ref: '#/definitions/Icon'
  Category:
    title: Category
    description: Model for a Category.
    type: object
    properties:
      id:
        type: number
        format: integer
        description: Category ID.
      name:
        type: string
        description: Category name.
  IdReference:
    title: Id-Reference to another object
    type: object
    properties:
      id:
        type: number
        format: integer
        description: ID of the Another Object.
  IdAndUUIDReference:
    title: Id and UUID Reference to another object
    type: object
    properties:
      id:
        type: number
        format: integer
        description: ID of the Another Object.
      uuid:
        type: string
        description: UUID of the Another Object.
parameters:
  sizeParam:
    name: size
    in: query
    description: Size of the returned array
    type: number
    format: integer
  pageParam:
    name: page
    in: query
    description: Page index
    type: number
    format: integer
  sortParam:
    name: sort
    in: query
    description: Field to sort by. (Use a +/- prefix for ascending/descending order)
    type: string
  fieldsParam:
    name: fields
    in: query
    description: 'Fields to return, separated by commas'
    type: string
responses:
  success:
    description: Successful response
  notFound:
    description: Requested object not found
  resourceArray:
    description: Resource Array
    schema:
      type: array
      items:
        $ref: '#/definitions/Resource'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer
  authorArray:
    description: Author Array
    schema:
      type: array
      items:
        $ref: '#/definitions/Author'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer
  categoryArray:
    description: Category Array
    schema:
      type: array
      items:
        $ref: '#/definitions/Category'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer
  versionArray:
    description: Version Array
    schema:
      type: array
      items:
        $ref: '#/definitions/ResourceVersion'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer
  updateArray:
    description: Update Array
    schema:
      type: array
      items:
        $ref: '#/definitions/ResourceUpdate'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer
  reviewArray:
    description: Review Array
    schema:
      type: array
      items:
        $ref: '#/definitions/ResourceReview'
    headers:
      X-Page-Sort:
        description: Field the elements are sorted by
        type: string
      X-Page-Order:
        description: Sort order
        type: integer
      X-Page-Size:
        description: Number of elements on the current page
        type: integer
      X-Page-Index:
        description: Current page index
        type: integer
      X-Page-Count:
        description: Total amount of pages
        type: integer