Sequence Diagrams

Authentication

Authentication uses Machine-to-Machine (M2M) AWS Cognito to generate a bearer token for subsequent API calls. See the Authentication guide for details on calling the Authorisation Endpoint.

Warning: The returned token must not be exposed outside your server, as any caller with this bearer token can access all of your users' data.

sequenceDiagram
  participant User as User
  participant Client as Your Server
  participant CogoAuth as Authorisation Endpoint
  participant CogoApi as Cogo API

  %% Authentication
  User->>+Client: Query your server
  Client->>+CogoAuth: POST obtain token
  Note left of CogoAuth: Base64 encoded client_id and client_secret
  CogoAuth->>-Client: 200 response with access_token

  %% Example Usage
  loop one or more calls to API to answer customer query
    Client->>+CogoApi: Call API with header `Authorization: Bearer `
    alt expired or invalid token
      CogoApi->>-Client: 401 Forbidden
    else valid token
      activate CogoApi
      CogoApi->>-Client: 2XX Response
    end
  end
  Client->>-User: customised response

Carbon Footprinting

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API

  A->>B: GET List transaction categories
  Note over B: Retrieve latest categories from datapack
  B->>A: 200 response

  A->>B: POST Submit new transactions
  Note over B: Parse and validate transactions
  Note over B: Read user file
  Note over B: Perform top-up enrichment
  Note over B: Calculate carbon footprint & transactional savings
  Note over B: Insert new transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

  A->>B: GET Query transactions
  Note over B: Read user file
  Note over B: Apply query parameters
  B->>A: 200 response

  A->>B: GET Query monthly totals
  Note over B: Read user file
  Note over B: Perform aggregation based on given params
  Note over B: Calculate recommended carbon budget based on users' recent transactions
  Note over B: Retrieve the user's budget histories
  B->>A: 200 response

  rect rgba(0, 0, 255, .1)
    A->>B: GET Query totals
    Note over B: Read user file
    Note over B: Perform aggregation based on given params
    Note over B: Calculate recommended carbon budget based on users' recent transactions
    Note over B: Retrieve the user's budget histories
    B->>A: 200 response
  end

Quantified Climate Actions

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API

  A->>B: GET List questions
  Note over B: retrieve latest questions from datapack
  B->>A: 200 response

  A->>B: GET List actions
  Note over B: retrieve latest actions, including required & optional questions, from datapack
  B->>A: 200 response

  A->>B: PUT Create/Update responses
  Note over B: Parse and validate responses
  Note over B: Read user file
  Note over B: Merge new and existing responses
  Note over B: Find transactions impacted by the updated responses
  Note over B: Recalculate carbon footprint & transactional savings
  Note over B: Insert impacted transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

  A->>B: GET Query responses
  Note over B: Read user file
  Note over B: Extract responses
  B->>A: 200 response

  A->>B: GET Query user actions
  Note over B: Read user file
  Note over B: Perform aggregation based on given params
  Note over B: Extract responses
  Note over B: Repeat aggregation for projected savings, based on the last 90 days
  Note over B: Load all actions and enrich with aggregation results
  B->>A: 200 response

  A->>B: GET Query non-transactional savings
  Note over B: Read user file
  Note over B: Retrieve user's responses
  Note over B: Calculate savings based on given period & responses
  B->>A: 200 response

Carbon Budgets

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API

  A->>B: Set budget
  Note over B: Parse and validate budget
  Note over B: Read user file
  Note over B: Append new budget
  Note over B: Save user file
  B->>A: 200 response

  A->>B: GET Query budget
  Note over B: Read user file
  Note over B: Retrieve current budget
  Note over B: Calculate recommended carbon budget based on users' recent transactions
  B->>A: 200 response

  A->>B: GET Query streak length
  Note over B: Read user file
  Note over B: Load all user's transactions & budgets
  Note over B: Count consecutive months where user spends under that month's carbon budget
  B->>A: 200 response

Submitting and editing transactions

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API

  A->>B: POST submit new transactions and ignore existing transactions
  Note over B: Parse and validate transactions
  Note over B: Read user file
  Note over B: Perform top-up enrichment
  Note over B: Calculate carbon footprint & transactional savings
  Note over B: Insert new transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

  A->>B: PUT Submit new transactions and update existing transactions
  Note over B: Parse and validate transactions
  Note over B: Read user file
  Note over B: Perform top-up enrichment
  Note over B: Calculate carbon footprint & transactional savings
  Note over B: Upsert new transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

  A->>B: PATCH Update existing transactions
  Note over B: Parse and validate transactions
  Note over B: Read user file
  Note over B: Extract all existing transactions
  Note over B: Merge new and existing transactions
  Note over B: Perform top-up enrichment
  Note over B: Recalculate carbon footprint & transactional savings
  Note over B: Insert updated transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

  A->>B: PATCH Update transactions by query with a delta
  Note over B: Parse and validate query
  Note over B: Read user file
  Note over B: Retrieve transactions matching query
  Note over B: Apply delta to filtered transactions
  Note over B: Perform top-up enrichment
  Note over B: Recalculate carbon footprint & transactional savings
  Note over B: Insert updated transactions, footprint, and savings
  Note over B: Save user file
  B->>A: 200 response

User management

User creation is automatic. On every request, the API fetches the user file from storage. If no file exists, a new one is created.

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API
  participant C as Storage

  A-->>B: Every request
  alt existing user
    B->>C: Read user file
    C->>B: User file
  else new user
    B->>C: Read user file
    C->>B: No user file found
    B->>C: Save blank user file
    C->>B: User file
  end
  Note over B: Process request...

All user data can be deleted with a single call.

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API
  participant C as Storage

  A->>B: DELETE user
  B->>C: Delete user
  Note over C: Delete user file
  C->>B: File deleted
  B->>A: 200 response

User account management

sequenceDiagram
  participant A as Your Server
  participant B as Cogo API

  A->>B: GET Query user account
  Note over B: Read user file
  Note over B: Extract configuration for the requested account
  B->>A: 200 response

  A->>B: GET Query user accounts
  Note over B: Read user file
  Note over B: Extract configuration for all accounts
  B->>A: 200 response

  A->>B: PUT Update account configuration
  Note over B: Validate new configuration
  Note over B: Read user file
  Note over B: Update existing configuration
  Note over B: Save user file
  B->>A: 200 response