rest-api.yaml

---
openapi: 3.0.0

info:
  description: |
    API specification for the Collectme V2 WordPress plugin.
    
    **Authentication**
    
    Users may authenticate themselves using the `POST /api/auth` or `GET /app?action=create` endpoints. Authentication 
    works with the following two cookies: 
    
    - `WP_COLLECTME_AUTH`: Persistent login. Cookie contains the persistent session's `uuid` and a secret that 
      corresponds to the `session_hash`.
    - `PHPSESSID`: Session login. Cookie contains the PHP session id.
    
    While `WP_COLLECTME_AUTH` keeps the user logged in (for 5 years), the session cookie has a short ttl (default 
    session duration) but better performance. The session cookie therefore takes precedence over the `WP_COLLECTME_AUTH`
    cookie. Both cookies must be deleted, to log the user out.
    
    See [/docs/uml/login-flow.puml](/docs/uml/login-flow.puml) for a diagram of the login flow.
    
    All protected functions do also need a nonce for CSRF protection. The nonce must be sent in the 
    `X-WP-Nonce` header. It can be obtained from the global JS variable `collectme.nonce`, which is set by the 
    `HtmlController`.

    **URLs**
    
    - `/api` is a placeholder for the api prefix. With pretty permalinks, this will be `/wp-json/collectme/v1`. It is
      passed to the app via the global JS variable `collectme.apiBaseUrl`.
    - `/app` is a placeholder for the url of the page or post where the plugin is used (via shortcode). It is passed to
      the app via the global JS variable `collectme.appUrl`.
    

  version: 1.0.0
  title: Collectme V2
  contact:
    email: admin@gruene.ch
  license:
    name: LGPL-3.0
    url: 'https://opensource.org/licenses/LGPL-3.0'

servers:
  - description: Prism Mock API
    url: http://localhost:8040/

tags:
  - name: users
  - name: auth
    description: authentication
  - name: sessions
    description: persistent sessions
  - name: groups
    description: signature groups
  - name: stats
    description: statistics
  - name: signatures
    description: signature entries
  - name: objectives
    description: pledges and quotas
  - name: activities
    description: activity feed


components:
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'

  schemas:
    # --------------------------------------------------------------------------
    # ModelBase
    # --------------------------------------------------------------------------

    ActivityBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: activity
          readOnly: true

    CauseBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: cause
          readOnly: true

    GroupBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: group
          readOnly: true

    ObjectiveBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: objective
          readOnly: true

    RoleBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: role
          readOnly: true

    SessionBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: session
          readOnly: true

    SignatureBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: signature
          readOnly: true

    StatBase:
      type: object
      required: [ id, type ]
      properties:
        id:
          type: string
          example: overview-5883e513-082d-4b16-80b2-c21b6bc18ed4
          readOnly: true
        type:
          type: string
          example: stat
          readOnly: true

    UserBase:
      type: object
      required: [id, type]
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          example: user
          readOnly: true


    # --------------------------------------------------------------------------
    # ModelAttributes
    # --------------------------------------------------------------------------

    ActivityAttributes:
      type: object
      required:
        - type
        - count
        - created
        - updated
      properties:
        type:
          type: string
          enum:
            - pledge
            - personal signature
            - organization signature
            - personal goal achieved
            - personal goal raised
        count:
          type: integer
          example: 55
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    GroupAttributes:
      type: object
      required:
        - name
        - type
        - signatures
        - writeable
        - created
        - updated
      properties:
        name:
          type: string
          example: Maria Muster
        type:
          type: string
          enum: [ person, organization ]
        signatures:
          type: integer
          example: 45
          description: Computed. The total amount of signatures of this group.
          readOnly: true
        writeable:
          description: Computed. Tells if the current user has write permission for this group.
          type: boolean
          example: true
          readOnly: true
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    LoginAttributes:
      type: object
      required:
        - email
        - firstName
        - lastName
        - created
        - updated
      properties:
        email:
          type: string
          format: email
        firstName:
          type: string
          example: Maria
        lastName:
          type: string
          example: Muster
        appUrl:
          type: string
          format: url
        urlAuth:
          type: string
          format: hash
          description: Salted hash of `appUrl`.

    ObjectiveAttributes:
      type: object
      required:
        - objective
        - source
        - created
        - updated
      properties:
        objective:
          type: integer
          example: 200
        source:
          type: string
          example: Newsletter
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    RoleAttributes:
      type: object
      required:
        - permission
        - created
        - updated
      properties:
        permission:
          type: string
          enum: [ r, rw ]
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    SessionAttributes:
      type: object
      required:
        - loginCounter
        - lastLogin
        - activated
        - created
        - updated
      properties:
        loginCounter:
          type: integer
          example: 0
        lastLogin:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        activated:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    SignatureAttributes:
      type: object
      required:
        - count
        - created
        - updated
      properties:
        count:
          type: integer
          example: 13
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true

    StatAttributes:
      type: object
      required:
        - pledged
        - registered
        - updated
      properties:
        pledged:
          type: number
          example: 0.173
          readOnly: true
          description: | 
            Fraction of needed pledges to actual pledges.
            Only the highest pledge for each group (of type person) is counted.
            Multiply by 100 to get the percentage.
        registered:
          type: number
          example: 0.304
          readOnly: true
          description: |
            Fraction of needed signatures to registered signatures.
            Sum of all signatures from groups of type 'person'.
            Multiply by 100 to get the percentage.
        updated:
          type: string
          format: date-time
          readOnly: true
          description: |
            Last time the statistics cache was updated.

    UserAttributes:
      type: object
      required:
        - email
        - firstName
        - lastName
        - lang
        - created
        - updated
      properties:
        email:
          type: string
          format: email
        firstName:
          type: string
          example: Maria
        lastName:
          type: string
          example: Muster
        lang:
          type: string
          enum: [ d, f, e ]
        created:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        updated:
          type: string
          format: date-time
          nullable: true
          readOnly: true


    # --------------------------------------------------------------------------
    # Models
    # --------------------------------------------------------------------------

    Activity:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: activity
        attributes:
          $ref: '#/components/schemas/ActivityAttributes'
        relationships:
          $ref: '#/components/schemas/RelatedGroup'

    Group:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: group
        attributes:
          $ref: '#/components/schemas/GroupAttributes'
        relationships:
          allOf:
            - $ref: '#/components/schemas/RelatedObjectives'
            - $ref: '#/components/schemas/RelatedRoles'
            - $ref: '#/components/schemas/RelatedCause'

    Login:
      required:
        - type
        - attributes
        - relationships
      type: object
      properties:
        type:
          type: string
          readOnly: true
          example: login
        attributes:
          $ref: '#/components/schemas/LoginAttributes'
        relationships:
          $ref: '#/components/schemas/RelatedCause'

    Objective:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: objective
        attributes:
          $ref: '#/components/schemas/ObjectiveAttributes'
        relationships:
          $ref: '#/components/schemas/RelatedGroup'

    Role:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: role
        attributes:
          $ref: '#/components/schemas/RoleAttributes'
        relationships:
          allOf:
            - $ref: '#/components/schemas/RelatedUser'
            - $ref: '#/components/schemas/RelatedGroup'

    Session:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: session
        attributes:
          $ref: '#/components/schemas/SessionAttributes'
        relationships:
          $ref: '#/components/schemas/RelatedUser'

    Signature:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: signature
        attributes:
          $ref: '#/components/schemas/SignatureAttributes'
        relationships:
          allOf:
            - $ref: '#/components/schemas/RelatedUser'
            - $ref: '#/components/schemas/RelatedGroup'
            - $ref: '#/components/schemas/RelatedActivity'

    Stat:
      required:
        - id
        - type
        - attributes
      type: object
      properties:
        id:
          type: string
          example: overview
          readOnly: true
        type:
          type: string
          example: stat
          readOnly: true
        attributes:
          $ref: '#/components/schemas/StatAttributes'
        relationships:
          $ref: '#/components/schemas/RelatedCause'

    User:
      required:
        - id
        - type
        - attributes
        - relationships
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          readOnly: true
        type:
          type: string
          readOnly: true
          example: user
        attributes:
          $ref: '#/components/schemas/UserAttributes'


    # --------------------------------------------------------------------------
    # Related Models
    # --------------------------------------------------------------------------

    RelatedActivity:
      type: object
      required: [activity]
      properties:
        activity:
          type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/ActivityBase'

    RelatedActivities:
      type: object
      required: [ activity ]
      properties:
        activity:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ActivityBase'
    
    RelatedCause:
      type: object
      required: [ cause ]
      properties:
        cause:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/CauseBase'
    
    RelatedCauses:
      type: object
      required: [ cause ]
      properties:
        cause:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CauseBase'
    
    RelatedGroup:
      type: object
      required: [ group ]
      properties:
        group:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/GroupBase'
      
    RelatedGroups:
      type: object
      required: [ group ]
      properties:
        group:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/GroupBase'

    RelatedObjective:
      type: object
      required: [ objective ]
      properties:
        objective:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/ObjectiveBase'
    
    RelatedObjectives:
      type: object
      required: [ objective ]
      properties:
        objective:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ObjectiveBase'
    
    RelatedRole:
      type: object
      required: [ role ]
      properties:
        role:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/RoleBase'
    
    RelatedRoles:
      type: object
      required: [ role ]
      properties:
        role:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/RoleBase'

    RelatedSession:
      type: object
      required: [ session ]
      properties:
        session:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/SessionBase'
    
    RelatedSessions:
      type: object
      required: [ session ]
      properties:
        session:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SessionBase'
    
    RelatedSignature:
      type: object
      required: [ signature ]
      properties:
        signature:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/SignatureBase'
      
    RelatedSignatures:
      type: object
      required: [ signature ]
      properties:
        signature:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/SignatureBase'

    RelatedStat:
      type: object
      required: [ stat ]
      properties:
        stat:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/StatBase'

    RelatedUser:
      type: object
      required: [ user ]
      properties:
        user:
          type: object
          required: [ data ]
          properties:
            data:
              $ref: '#/components/schemas/UserBase'

    RelatedUsers:
      type: object
      required: [ user ]
      properties:
        user:
          type: object
          required: [ data ]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserBase'

    # --------------------------------------------------------------------------
    # Misc
    # --------------------------------------------------------------------------

    PaginationLinks:
      type: object
      properties:
        first:
          type: string
          format: url
          example: "/causes/e3c9f7c1-3fc6-4e71-9cf5-dd09b93cd771/activities"
          nullable: true
          readOnly: true
        last:
          type: string
          format: url
          nullable: true
          example: null
          readOnly: true
        prev:
          type: string
          format: url
          nullable: true
          example: "/causes/e3c9f7c1-3fc6-4e71-9cf5-dd09b93cd771/activities?page[cursor]=3fa85f64-5717-4562-b3fc-2c963f66afa6"
          readOnly: true
        next:
          type: string
          format: url
          nullable: true
          example: "/causes/e3c9f7c1-3fc6-4e71-9cf5-dd09b93cd771/activities?page[cursor]=3fa85f64-5717-4562-b3fc-2c963f66afa6"
          readOnly: true

    # --------------------------------------------------------------------------
    # Errors
    # --------------------------------------------------------------------------

    ErrorModel:
      type: object
      properties:
        status:
          type: integer
          example: 400
          readOnly: true
        title:
          type: string
          example: Bad Request
          readOnly: true
        detail:
          type: string
          example: The request was malformed.
          readOnly: true
        source:
          type: object
          properties:
            pointer:
              type: string
              example: /data/attributes/name
              readOnly: true
            parameter:
              type: string
              example: token
              readOnly: true
        meta:
          type: object
          properties:
            exception:
              type: string
              example: CollectmeDbException
              readOnly: true

    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorModel'

    InvalidEmail:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                example: 422
              title:
                type: string
                example: Unprocessable Entity
              source:
                type: object
                properties:
                  pointer:
                    type: string
                    example: "/data/attributes/email"

    InvalidToken:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                example: 404
              title:
                type: string
                example: Invalid Token

    NotFound:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                example: 404
              title:
                type: string
                example: Not Found


    Unauthorized:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                example: 401
              title:
                type: string
                example: Unauthorized

  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: PHPSESSID

  parameters:
    uuid:
      name: uuid
      in: path
      required: true
      description: Uuid of the previous element in the path
      schema:
        type: string
        format: uuid

paths:
  /api/users/me:
    get:
      tags:
        - users
      summary: Get logged in user
      description: |
        Retreives the user object of the currently logged in user.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/auth:
    post:
      tags:
        - auth
      summary: Post user data and receive an activation link by email
      description: |
        - Create user if it doesn't exist.
        - Create not activated session for user.
        - Send the user an email with a link to activate the session.
        - Set the `WP_COLLECTME_AUTH` cookie in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Login'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Session'
          headers:
            Location:
              description: /sessions/{uuid}
              schema:
                type: string
            Set-Cookie:
              description: |
                WP_COLLECTME_AUTH='{sessionUuid sessionSecret}'; Secure; HttpOnly; SameSite=Strict; Expires=Tue, 01 Jan 2030 00:00:00 GMT
              schema:
                type: string
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidEmail'

  /app:
    get:
      parameters:
        - name: action
          in: query
          schema:
            type: string
            enum:
              - activate
              - create
          required: true
        - name: token
          description: The `token`
          in: query
          schema:
            type: string
            minLength: 64
            maxLength: 64
          required: true
        - name: email
          in: query
          schema:
            type: string
            format: email
          description: Required for `create` action
        - name: session
          in: query
          schema:
            type: string
            format: uuid
          description: Required for `activate` action
      tags:
        - auth
      summary: Activate session OR Authenticate user
      description: |
        **Note:** This endpoint doesn't target the API but the pages permalink. It is therefore not handled by the
        RestRouter but the ShortcodeHandler.
        
        **If `action=activate`:**
        - Check token (`$persistentSession->activationSecret`) and activate session if valid.
        - **No** WP_COLLECTME_AUTH cookie set. The request only activates the session, but doesn't authenticate the user.
          User authentication must be done in the browser that called the `/api/auth` endpoint.
        - The browser must display a message to the user that the session has been activated in the browser that called
          the `/api/auth` endpoint.
        
        Counterpart of the `/api/auth` endpoint.
        
        **If `action=create`:**
        - Check token (`$accountToken->token`). If valid:
          - Create user if it doesn't exist.
          - Create activated session for user.
          - Set the `WP_COLLECTME_AUTH` cookie in the response.
        
        Used for direct login links manually prepared in the account tokens table.
      responses:
        '200':
          description: |
            **If `action=activate`:**
            - A message telling the user that he is now logged in in the browser that he used to register.
            
            **If `action=create`:**
            - The app.
            - If an account token was found, the user is logged in.
            - If no account token was found, the user sees the app like a regular visitor and is therefore prompted to
              register. If he does so, he is directed to `/api/auth` -> `/app?action=activate` flow.
          content:
            text/html:
              schema:
                type: string

          headers:
            Set-Cookie:
              description: |
                WP_COLLECTME_AUTH='{sessionUuid sessionSecret}'; Secure; HttpOnly; SameSite=Strict; Expires=Tue, 01 Jan 2030 00:00:00 GMT
              schema:
                type: string

  /api/sessions/current:
    get:
      tags:
        - sessions
      summary: Get current user's persistent session
      description: |
        May be used to check the user's login state if `WP_COLLECTME_AUTH` cookie is set. If the persistent session 
        exists but waits for activation, a `401` is returned. It the persistent session was not found, deleted or 
        closed, the api responds with a `404`.
      responses:
        '200':
          description: OK
          headers:
            Set-Cookie:
              description: PHPSESSID
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Session'
        '401':
          description: The permanent session was not yet activated. Keep polling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: The permanent session was closed or not found. Please log in again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      security:
        - cookieAuth: [ ]

  /api/sessions/{uuid}:
    parameters:
      - $ref: '#/components/parameters/uuid'

    delete:
      tags:
        - sessions
      summary: Logout
      description: |
        Closes the persistent session in the database and removes the PHP session on the server. Additionally, the response contains cookie expiration headers for the client.
      responses:
        '204':
          description: OK
          headers:
            Set-Cookie:
              description: |
                WP_COLLECTME_AUTH=''; Max-Age=0
              schema:
                type: string
            "\0Set-Cookie":
              description: |
                PHPSESSID=''; Max-Age=0
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/causes/{uuid}/groups:
    parameters:
      - $ref: '#/components/parameters/uuid'

    get:
      tags:
        - groups
      summary: List of groups this user can view
      description: |
        Get an array with all groups, the current user has read permission for.
        
        Using a non-existing cause uuid returns an empty array.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
                  included:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/Objective'
                        - $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/causes/{uuid}/stats:
    parameters:
      - $ref: '#/components/parameters/uuid'

    get:
      tags:
        - stats
      summary: Statistics
      description: Percentage of pledged and registered signatures
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stat'
      security:
        - cookieAuth: [ ]

  /api/signatures:
    post:
      tags:
        - signatures
      summary: Add signature entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Signature'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Signature'
          headers:
            Location:
              description: /signatures/{uuid}
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/signatures/{uuid}:
    parameters:
      - $ref: '#/components/parameters/uuid'

    delete:
      tags:
        - signatures
      summary: Remove signature entry
      responses:
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/objectives:

    post:
      tags:
        - objectives
      summary: Add objective
      description: |
        Adds a new objective. The objective with the highest count is the 
        authorative one.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/Objective'
      responses:
        '200':
          description: An objective with the same objective value already exists. See response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Objective'
          headers:
            Location:
              description: /objectives/{uuid}
              schema:
                type: string
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Objective'
          headers:
            Location:
              description: /objectives/{uuid}
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]

  /api/causes/{uuid}/activities:
    parameters:
      - $ref: '#/components/parameters/uuid'

    get:
      tags:
        - activities
      parameters:
        - name: page[cursor]
          description: |
            The uuid of the latest activity of the page to retrieve or null to
            get the page with the latest activities.
          in: query
          schema:
            type: string
            minLength: 36
            maxLength: 36
        - name: page[points]
          description: |
            Indicates if the cursor points to the first or the last entry of the page.
            If the last is given, the server will respond with the next entries, for
            the first, the server will respond with the previous entries.
          in: query
          schema:
            type: string
            enum:
              - first
              - last
            default: last
        - name: filter
          description: |
            Filter expression. Currently the only implemented filter is
            `filter[count]=gt(x)`, where `x` denotes the number of signatures
            and `gt()` the greater than function.
          in: query
          schema:
            type: string
            example: filter[count]=gt(0)
          required: false

      summary: Get activities
      description: Paginated list of activities, sorted by creation date, newest first.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  included:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - cookieAuth: [ ]