openapi: 3.1.0
info:
  version: '1'
  title: GUID as a Service
  description: >
    A convenient web service for generating GUIDs in a enterprisy way.
    See [https://gaas.cooperjr.name/](https://gaas.cooperjr.name/)
    for more information.
servers:
  - url: https://api.gaas.cooperjr.name
paths:
  /:
    get:
      summary: Make a GUID request
      parameters:
        - name: type
          in: query
          schema:
            type: number
            enum: 
              - 1
              - 4
              - 6
              - 7
          description: |
            This specifies what type of GUID to generate.
            Valid values are
            
            * `1`: A Version 1 GUID based on timestamp and a MAC address
            * `4`: A Version 4 GUID based on random numbers
            * `6`: A Version 6 GUID based on timestamp and a MAC address, but in a different ordering of fields than Version 1 to improve database locality
            * `7`: A Version 7 GUID based on timestamp and random numbers together
            
            If not specified, you must not care what type of GUID you get.

            For more details on the different GUID versions, refer to
            [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562.html).
        - name: count
          in: query
          schema:
            type: number
            minimum: 0
            maximum: 1000
          description: >
            If you specify this parameter, instead of returning a single String with a new GUID, generate the number of GUIDs you specify and return it as a JSON array. Note that if you specify 1, it will still be returned in an array, even though only one GUID will be in it. (As opposed to when this parameter is not specified, where a single String is returned but not in an array.)
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                oneOf: 
                  - type: string
                    format: uuid
                    summary: The new GUID
                    description: >
                      An artisinal new GUID, made just for you. This single string
                      is what gets returned if you do not pass the "count" parameter
                  - type: array
                    summary: An array of new GUIDs
                    description: >
                      An array full of new GUIDs. The length will be the number
                      passed in the "count" query argument. The array only
                      gets returned when you do pass the "count" parameter.
                    items: 
                      type: string
                      format: uuid