openapi.yml

openapi: "3.0.2"
info:
  title: API documentation
  description: The official source of placeholder.app API documentation.
  version: "1.0.0"
servers:
  - url: https://api.placeholder.app
    description: Production API Server
  - url: http://localhost:8080
    description: Local API Test Server
paths:
  /status:
    get:
      operationId: /status
      summary: Output current service status
      description: Returns a JSON object with information pertaining to the current service status
      responses:
        "200":
          description: Successful query
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: OK
                  notice:
                    type: string
                    example: Update to backend API releasing on 2022-12-24.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
  /image/fonts:
    get:
      operationId: /image/fonts
      summary: List supported image fonts
      description: Returns a list of all supported placeholder image fonts usable. No parameters supported.
      responses:
        "200":
          description: Successful query
          content:
            application/json:
              schema:
                type: object
                title: Result
                properties:
                  status:
                    title: API Status Message
                    type: object
                    example: ok
                  fonts:
                    title: Font Array
                    type: array
                    items:
                      type: string
                      title: Font Name
                      example: Sans-Serif
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
  /image/formats:
    get:
      operationId: /image/formats
      summary: List supported image formats
      description: Returns a list of all supported placeholder image formats usable. No parameters supported.
      responses:
        "200":
          description: Successful query
          content:
            application/json:
              schema:
                type: object
                title: Result
                properties:
                  status:
                    title: API Status Message
                    type: object
                    example: ok
                  formats:
                    title: Font Array
                    type: array
                    items:
                      type: string
                      title: Format Name
                      example: jpg
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
  /image/{size}:
    get:
      operationId: /image/{size}
      summary: Output a placeholder image
      description: Returns a placeholder image defined by the path parameters.
      parameters:
        - name: size
          in: path
          required: true
          schema:
            type: string
            example: 400x400
            description: >
              A WxH string deliniated by "x"
              Width and Height are integers, must be no larger than 4000px and no smaller than 30px
              Width and Height will be rounded to the nearest 5px
        - name: text
          in: query
          required: false
          schema:
            type: string
            example: Hello World
            description: An optional query parameter containing text to place at the center of the image
        - name: font
          in: query
          required: false
          schema:
            type: string
            example: CalSansSemiBold
            description: An optional query parameter containing the font-family to use during image generation. See /fonts
        - name: borderWidth
          in: query
          required: false
          schema:
            type: integer
            example: 10
            description: An optional query parameter that specifies the image border width in pixels
        - name: borderColor
          in: query
          required: false
          schema:
            type: string
            example: FF0000
            description: An optional query parameter that specifies the border color.
        - name: format
          in: query
          required: false
          schema:
            type: string
            example: png
            description: An option query parameter that specifies the output image format. See /image/formats
      responses:
        "200":
          description: Image Created
          content:
            application/json:
              schema:
                type: object
                description: Base64 encoded image output.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "400":
          description: The parameters passed are invalid or unacceptable.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "500":
          description: An unknown server error occured, retry later.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
  /image/{size}/{bgColor}:
    get:
      operationId: /image/{size}/{bgColor}
      summary: Output a placeholder image
      description: Returns a placeholder image defined by the path parameters.
      parameters:
        - name: size
          in: path
          required: true
          schema:
            type: string
            example: 400x400
            description: >
              A WxH string deliniated by "x"
              Width and Height are integers, must be no larger than 4000px and no smaller than 30px
              Width and Height will be rounded to the nearest 5px
        - name: bgColor
          in: path
          required: true
          schema:
            type: string
            example: 3B3B3B
            description: A HEX string containing the desired background color for the image. Must not contain the hash-prefix ("#3b3b3b")
        - name: text
          in: query
          required: false
          schema:
            type: string
            example: Hello World
            description: An optional query parameter containing text to place at the center of the image
        - name: font
          in: query
          required: false
          schema:
            type: string
            example: Sans-Serif
            description: An optional query parameter containing the font-family to use during image generation. See /fonts
        - name: borderWidth
          in: query
          required: false
          schema:
            type: integer
            example: 10
            description: An optional query parameter that specifies the image border width in pixels
        - name: borderColor
          in: query
          required: false
          schema:
            type: string
            example: FF0000
            description: An optional query parameter that specifies the border color.
        - name: format
          in: query
          required: false
          schema:
            type: string
            example: png
            description: An option query parameter that specifies the output image format. See /image/formats
      responses:
        "200":
          description: Image Created
          content:
            application/json:
              schema:
                type: object
                description: Base64 encoded image output.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "400":
          description: The parameters passed are invalid or unacceptable.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "500":
          description: An unknown server error occured, retry later.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
  /image/{size}/{bgColor}/{txtColor}:
    get:
      operationId: /image/{size}/{bgColor}/{txtColor}
      summary: Output a placeholder image
      description: Returns a placeholder image defined by the path parameters.
      parameters:
        - name: size
          in: path
          required: true
          schema:
            type: string
            example: 400x400
            description: >
              A WxH string deliniated by "x"
              Width and Height are integers, must be no larger than 4000px and no smaller than 30px
              Width and Height will be rounded to the nearest 5px
        - name: bgColor
          in: path
          required: true
          schema:
            type: string
            example: 3B3B3B
            description: A HEX string containing the desired background color for the image. Must not contain the hash-prefix ("#3b3b3b")
        - name: txtColor
          in: path
          required: true
          schema:
            type: string
            example: FFFFFF
            description: A HEX string containing the desired text color for the image. Must not contain the hash-prefix ("#FFFFFF")
        - name: text
          in: query
          required: false
          schema:
            type: string
            example: Hello World
            description: An optional query parameter containing text to place at the center of the image
        - name: font
          in: query
          required: false
          schema:
            type: string
            example: Sans-Serif
            description: An optional query parameter containing the font-family to use during image generation. See /fonts
        - name: borderWidth
          in: query
          required: false
          schema:
            type: integer
            example: 10
            description: An optional query parameter that specifies the image border width in pixels
        - name: borderColor
          in: query
          required: false
          schema:
            type: string
            example: FF0000
            description: An optional query parameter that specifies the border color.
        - name: format
          in: query
          required: false
          schema:
            type: string
            example: png
            description: An option query parameter that specifies the output image format. See /image/formats
      responses:
        "200":
          description: Image Created
          content:
            application/json:
              schema:
                type: object
                description: Base64 encoded image output.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "400":
          description: The parameters passed are invalid or unacceptable.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
        "500":
          description: An unknown server error occured, retry later.
          headers:
            X-Rate-Limit-Limit:
              $ref: '#/components/headers/X-Rate-Limit-Limit'
            X-Rate-Limit-Remaining:
              $ref: '#/components/headers/X-Rate-Limit-Remaining'
components:
  headers:
    X-Rate-Limit-Limit:
      description: Request limit per minute
      schema:
        type: integer
      example: 10
    X-Rate-Limit-Remaining:
      schema:
        type: integer
      example: 3