openapi.yaml

openapi: 3.0.0

info:
  title: Emblem API
  description: REST API for any Emblem server
  version: '2021-09-01'

servers:
- url: https://example.com
  description: Development server

paths:
  /approvers:
    get:
      summary: Returns a list of approvers
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A JSON array of approvers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Approver'
        '403':
          description: Forbidden
        '404':
          description: not found. The path must have a typo
        default:
          description: Unexpected error

    post:
      summary: Create a new approver
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single approver
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Approver'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approver'
        '403':
          description: Forbidden
        '404':
          description: approvers must have been misspelled in path

  /approvers/{id}:
    get:
      summary: returns a single approver
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Approver Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON representation of a approver
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approver'
        '403':
          description: Forbidden
        '404':
          description: not found
        default:
          description: Unexpected error

    patch:
      summary: updates a single approver
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Approver Id
          required: true
          schema:
            type: string
      requestBody:
        description: JSON representation of a single approver
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Approver'
      responses:
        '201':
          description: JSON representation of a approver
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approver'
        '403':
          description: Forbidden
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

    delete:
      summary: deletes a single approver
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Approver Id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No content
        '403':
          description: Forbidden
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

  /campaigns:
    get:
      summary: Returns a list of campaigns
      responses:
        '200':
          description: A JSON array of campaigns
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Campaign'
        '404':
          description: not found. The path must have a typo
        default:
          description: Unexpected error

    post:
      summary: Create a new campaign
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single campaign
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Campaign'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '404':
          description: campaigns must have been misspelled in path

  /campaigns/{id}:
    get:
      summary: returns a single campaign
      parameters:
        - name: id
          in: path
          description: Campaign Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON representation of a campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '404':
          description: not found
        default:
          description: Unexpected error

    patch:
      summary: updates a single campaign
      parameters:
        - name: id
          in: path
          description: Campaign Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single campaign
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Campaign'
      responses:
        '201':
          description: JSON representation of a campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

    delete:
      summary: deletes a single campaign
      parameters:
        - name: id
          in: path
          description: Campaign Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No content
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

  /campaigns/{id}/donations:
    get:
      summary: lists all donations for the specified campaign
      parameters:
        - name: id
          in: path
          description: Campaign Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: JSON representation of an array of donations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Donation'
        '404':
          description: not found
        default:
          description: Unexpected error

  /causes:
    get:
      summary: Returns a list of causes
      responses:
        '200':
          description: A JSON array of causes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cause'
        '404':
          description: not found. The path must have a typo
        default:
          description: Unexpected error

    post:
      summary: Create a new cause
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single cause
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cause'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cause'
        '404':
          description: causes must have been misspelled in path

  /causes/{id}:
    get:
      summary: returns a single cause
      parameters:
        - name: id
          in: path
          description: Cause Id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JSON representation of a cause
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cause'
        '404':
          description: not found
        default:
          description: Unexpected error

    patch:
      summary: updates a single cause
      parameters:
        - name: id
          in: path
          description: Cause Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single cause
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Cause'
      responses:
        '201':
          description: JSON representation of a cause
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cause'
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

    delete:
      summary: deletes a single cause
      parameters:
        - name: id
          in: path
          description: Cause Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No content
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

  /donations:
    get:
      summary: Returns a list of donations
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A JSON array of donations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Donation'
        '404':
          description: not found. The path must have a typo
        default:
          description: Unexpected error

    post:
      summary: Create a new donation
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single donation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donation'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '404':
          description: donations must have been misspelled in path

  /donations/{id}:
    get:
      summary: returns a single donation
      parameters:
        - name: id
          in: path
          description: Donation Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: JSON representation of a donation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '404':
          description: not found
        default:
          description: Unexpected error

    patch:
      summary: updates a single donation
      parameters:
        - name: id
          in: path
          description: Donation Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single donation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donation'
      responses:
        '201':
          description: JSON representation of a donation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

    delete:
      summary: deletes a single donation
      parameters:
        - name: id
          in: path
          description: Donation Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No content
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

  /donors:
    get:
      summary: Returns a list of donors
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A JSON array of donors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Donor'
        '404':
          description: not found. The path must have a typo
        default:
          description: Unexpected error

    post:
      summary: Create a new donor or update existing donor with matching
        email address. Email address should uniquely specify a donor.
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single donor
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donor'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donor'
        '404':
          description: donors must have been misspelled in path

  /donors/{id}:
    get:
      summary: returns a single donor
      parameters:
        - name: id
          in: path
          description: Donor Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '200':
          description: JSON representation of a donor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donor'
        '404':
          description: not found
        default:
          description: Unexpected error

    patch:
      summary: updates a single donor
      parameters:
        - name: id
          in: path
          description: Donor Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      requestBody:
        description: JSON representation of a single donor
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Donor'
      responses:
        '201':
          description: JSON representation of a donor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donor'
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

    delete:
      summary: deletes a single donor
      parameters:
        - name: id
          in: path
          description: Donor Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '204':
          description: No content
        '404':
          description: not found
        '409':
          description: Conflict. If-Match header provided does not match current contents
        default:
          description: Unexpected error

  /donors/{id}/donations:
    get:
      summary: lists all donations for the specified donor
      parameters:
        - name: id
          in: path
          description: Donor Id
          required: true
          schema:
            type: string
      security:
        - bearerAuth: []
      responses:
        '201':
          description: JSON representation of an array of donations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Donation'
        '404':
          description: not found
        default:
          description: Unexpected error

components:
  schemas:
    Approver:
      required:
      - email
      properties:
        id:
          type: string
          readOnly: true
          description: unique, system-assigned identifier
        name:
          type: string
          nullable: true
          description: the display name of this Approver
        email:
          type: string
          description: the Approver's email address
        active:
          type: boolean
          default: false
          description: is this approver currently active?
        timeCreated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned creation timestamp
        updated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned update timestamp
        selfLink:
          type: string
          format: uri
          readOnly: true
          description: full URI of the resource

    Campaign:
      required:
      - name
      - cause
      properties:
        id:
          type: string
          readOnly: true
          description: unique, system-assigned identifier
        name:
          type: string
          description: the campaign's display name
        description:
          type: string
          default: "no description"
          description: the purpose of the campaign
        cause:
          type: string
          description: the id of the Cause this campaign is for
        managers:
          type: array
          default: []
          items:
            type: string
            format: email
            description: a manager's email address
        goal:
          type: number
          default: 0
          description: the fundraising goal, in USD
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: location of image to display for the campaign
        active:
          type: boolean
          default: false
          description: is this campaign accepting donations at this time?
        timeCreated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned creation timestamp
        updated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned update timestamp
        selfLink:
          type: string
          format: uri
          readOnly: true
          description: full URI of the resource

    Cause:
      required:
      - name
      properties:
        id:
          type: string
          readOnly: true
          description: unique, system-assigned identifier
        name:
          type: string
          description: the cause's display name
        description:
          type: string
          default: "no description"
          description: the purpose of the cause
        imageUrl:
          type: string
          format: uri
          nullable: true
          description: location of image to display for the cause
        active:
          type: boolean
          default: false
          description: is this cause accepting donations at this time?
        timeCreated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned creation timestamp
        updated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned update timestamp
        selfLink:
          type: string
          format: uri
          readOnly: true
          description: full URI of the resource

    Donation:
      required:
      - campaign
      - donor
      - amount
      properties:
        id:
          type: string
          readOnly: true
          description: unique, system-assigned identifier
        campaign:
          type: string
          description: the id of the campaign this donation is for
        donor:
          type: string
          description: the id of the donor this donation is from
        amount:
          type: number
          description: the amount donated, in USD
        timeCreated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned creation timestamp
        updated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned update timestamp
        selfLink:
          type: string
          format: uri
          readOnly: true
          description: full URI of the resource

    Donor:
      required:
      - name
      - email
      properties:
        id:
          type: string
          readOnly: true
          description: unique, system-assigned identifier
        name:
          type: string
          description: the display name of this donor
        email:
          type: string
          description: the donor's email address
        mailing_address:
          type: string
          nullable: true
          description: the donor's physical address
        timeCreated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned creation timestamp
        updated:
          type: string
          format: date-time
          readOnly: true
          description: system-assigned update timestamp
        selfLink:
          type: string
          format: uri
          readOnly: true
          description: full URI of the resource

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT