OBIE - Account and Transaction APIs.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Set up Account APIs\n",
    "Running this script will create the APIs that we will be monitoring for accounts and transactions. They require user authentication. \n",
    "\n",
    "The API setups are defined with tags that allow us to easily provide OBIE metric reporting.\n",
    "\n",
    "## Requirements\n",
    "1. Create an APImetrics Project\n",
    "1. Get an API key with EDITOR permissions for the project, enter it below\n",
    "1. Get the maTLS transport certificate and key in PEM format, enter paths below\n",
    "1. Run this workbook to create all APIs\n",
    "1. Create an environment variable \"financial_id\" - TBD - add this here\n",
    "\n",
    "NB: Until we publish a Conditions API, you will need to add conditions to the API to extract variables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Enter intended project's APImetrics API key here:\n",
    "API_KEY = input(\"Enter your APImetrics API key for the intended project\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Enter the bank's full path, including https and without trailing /\n",
    "BANK_URL = input(\"Enter the full URL path for the AISP APIs without trailing /: \") or 'https://example.com/open-banking/3.1/aisp'\n",
    "\n",
    "SSL_KEY_PATH = \"\" #\"./local/TPP_OB_Transport.key\"\n",
    "SSL_CERT_PATH = \"\" #\"./local/TTP_OB_Transport.pem\"\n",
    "\n",
    "# The OBIE version ID we're working against\n",
    "VERSION = \"3.1\"\n",
    "\n",
    "from urllib.parse import urlparse\n",
    "\n",
    "url_info = urlparse(BANK_URL)\n",
    "DOMAIN, _, _ = url_info.netloc.partition(':') # removes the port "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Helper functions\n",
    "import requests\n",
    "import json\n",
    "from apimetrics_api import APImetricsAPI \n",
    "\n",
    "# An instance of the class that calls the APImetrics API\n",
    "CLIENT = APImetricsAPI(API_KEY)\n",
    "\n",
    "# [CLIENT.delete_token(o['id']) for o in CLIENT.tokens.values()]\n",
    "# [CLIENT.delete_auth(o['id']) for o in CLIENT.auths.values()]\n",
    "# [CLIENT.delete_call(o['id']) for o in CLIENT.calls.values()]\n",
    "# [CLIENT.delete_workflow(o['id']) for o in CLIENT.workflows.values()]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "# All the account APIs share a similar setup, this is a mapping of\n",
    "# our tag to the OBIE tag, the path and the friendly name\n",
    "SETUP_MAP = {\n",
    "    \"bulk:accounts\": (4, \"/accounts\", \"Accounts: Bulk\"),\n",
    "    \"bulk:balances\": (7, \"/balances\", \"Balances: Bulk\"),\n",
    "    \"bulk:transactions\": (9, \"/transactions\", \"Transactions: Bulk\"),\n",
    "    \"bulk:beneficiaries\": (11, \"/beneficiaries\", \"Beneficiaries: Bulk\"),\n",
    "    \"bulk:directdebits\": (13, \"/direct-debits\", \"Direct-Debits: Bulk\"),\n",
    "    \"bulk:standingorders\": (15, \"/standing-orders\", \"Standing-Orders: Bulk\"),\n",
    "    \"bulk:products\": (17, \"/products\", \"Products: Bulk\"),\n",
    "    \"bulk:offers\": (19, \"/offers\", \"Offers: Bulk\"),\n",
    "    \"bulk:party\": (21, \"/party\", \"Party: Bulk\"),\n",
    "    \"bulk:scheduledpayments\": (23, \"/scheduled-payments\", \"Scheduled-Payments: Bulk\"),\n",
    "    \"bulk:statements\": (28, \"/statements\", \"Statements: Bulk\"),\n",
    "    \"account:account\": (5, \"/accounts/__ACCOUNT_ID__\", \"Accounts: Get for AccountId\"),\n",
    "    \"account:balance\": (6, \"/accounts/__ACCOUNT_ID__/balances\", \"Balances: Get for AccountId\"),\n",
    "    \"account:transactions\": (8, \"/accounts/__ACCOUNT_ID__/transactions\", \"Transactions: Get for AccountId\"),\n",
    "    \"account:beneficiaries\": (10, \"/accounts/__ACCOUNT_ID__/beneficiaries\", \"Beneficiaries: Get for AccountId\"),\n",
    "    \"account:directdebits\": (12, \"/accounts/__ACCOUNT_ID__/direct-debits\", \"Direct-Debits: Get for AccountId\"),\n",
    "    \"account:standingorders\": (14, \"/accounts/__ACCOUNT_ID__/standing-orders\", \"Standing-Orders: Get for AccountId\"),\n",
    "    \"account:product\": (16, \"/accounts/__ACCOUNT_ID__/product\", \"Product: Get for AccountId\"),\n",
    "    \"account:offers\": (18, \"/accounts/__ACCOUNT_ID__/offers\", \"Offers: Get for AccountId\"),\n",
    "    \"account:party\": (20, \"/accounts/__ACCOUNT_ID__/party\", \"Party: Get for AccountId\"),\n",
    "    \"account:scheduledpayments\": (22, \"/accounts/__ACCOUNT_ID__/scheduled-payments\", \"Scheduled-Payments: Get for AccountId\"),\n",
    "    \"account:statements\": (25, \"/accounts/__ACCOUNT_ID__/statements/__STATEMENT_ID__\", \"Statements: Get for StatementId\"),\n",
    "    \"account:statement\": (24, \"/accounts/__ACCOUNT_ID__/statements\", \"Statements: Get for AccountId\"),\n",
    "    \"account:statement_file\": (26, \"/accounts/__ACCOUNT_ID__/statements/__STATEMENT_ID__/file\", \"Statements: File for StatementId\"),\n",
    "    \"account:statement_transactions\": (27, \"/accounts/__ACCOUNT_ID__/statements/__STATEMENT_ID__/transactions\", \"Statements: Transactions for StatementId\"),\n",
    "}\n",
    "\n",
    "# Helper function - the APImetrics API setup object\n",
    "def get_call(ob_id, path, name, tag):\n",
    "    setup = {\n",
    "        \"meta\": {\n",
    "            \"description\": \"Get a list of accounts\",\n",
    "            \"tags\": [\n",
    "                \"api_type:read\",\n",
    "                \"sector:financial\",\n",
    "                \"ob_id:{}\".format(ob_id),\n",
    "                \"ob_v:{}\".format(VERSION),\n",
    "                tag,\n",
    "            ],\n",
    "            \"name\": \"v{}: {}\".format(VERSION, name),\n",
    "            \"workspace\": \"global\",\n",
    "        },\n",
    "        \"request\": {\n",
    "            \"body\": None,\n",
    "            \"parameters\": [],\n",
    "            \"url\": \"{}{}\".format(BANK_URL, path),\n",
    "            \"auth_id\": CLIENT.auths_by_tag['auth:bank_matls'],\n",
    "            \"headers\": [\n",
    "                {\"key\": \"Accept\", \"value\": \"application/json\"},\n",
    "                {\"key\": \"x-fapi-financial-id\", \"value\": \"{{financial_id}}\"},\n",
    "            ],\n",
    "            \"token_id\": CLIENT.tokens_by_auth[CLIENT.auths_by_tag['auth:bank_matls']],\n",
    "            \"method\": \"GET\",\n",
    "        },\n",
    "    }\n",
    "    return setup\n",
    "\n",
    "def get_call_setup(call_tag):\n",
    "    ob_id, path, name = SETUP_MAP[call_tag]\n",
    "    return get_call(ob_id, path, name, f\"banks:{VERSION}:{call_tag}\")\n",
    "\n",
    "def create_call_if_needed(tag):\n",
    "    if f\"banks:{VERSION}:{tag}\" not in CLIENT.calls_by_tag:\n",
    "        setup = get_call_setup(tag)\n",
    "        data = CLIENT.create_call(setup)\n",
    "        print(f\"Created API {data['meta']['name']} with id {data['id']}\")\n",
    "        return data['id']\n",
    "    return CLIENT.calls_by_tag[f\"banks:{VERSION}:{tag}\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Auth Setting and Token for Bank"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# # First create Auth Setting\n",
    "# tag = 'auth:bank_matls'\n",
    "# if tag not in CLIENT.auths_by_tag:\n",
    "\n",
    "#     ssl_key = None\n",
    "#     ssl_cert = None\n",
    "\n",
    "#     if SSL_KEY_PATH:\n",
    "#         with open(SSL_KEY_PATH) as stream:\n",
    "#             ssl_key = stream.read()\n",
    "\n",
    "#     if SSL_CERT_PATH:\n",
    "#         with open(SSL_CERT_PATH) as stream:\n",
    "#             ssl_cert = stream.read()\n",
    "    \n",
    "#     setup = {\n",
    "#         \"keys\": {},\n",
    "#         \"meta\": {\n",
    "#             \"domain\": DOMAIN,\n",
    "#             \"documentation\": {\"keys\": \"\", \"docs\": \"\", \"apps\": \"\", \"provider\": \"\"},\n",
    "#             \"name\": \"Transport MATLS\",\n",
    "#             \"tags\": [tag],\n",
    "#             \"description\": \"Mutual Authenticated TLS for calls to bank APIs\",\n",
    "#         },\n",
    "#         \"settings\": {\n",
    "#             \"auth_type\": \"MANUAL\",\n",
    "#             \"ssl_key\": ssl_key,\n",
    "#             \"ssl_cert\": ssl_cert,\n",
    "#         },\n",
    "#     }\n",
    "#     if OAUTH_METHOD == \"client_secret_post\" or OAUTH_METHOD == \"client_secret_basic\":\n",
    "#         setup[\"keys\"][\"client_id\"] = CLIENT_ID\n",
    "#         setup[\"keys\"][\"client_secret\"] = CLIENT_SECRET\n",
    "    \n",
    "#     auth = CLIENT.create_auth(setup)\n",
    "#     print(f\"Created Auth Setting {auth['meta']['name']} with id {auth['id']}\")\n",
    "    \n",
    "# # Second Create Token\n",
    "# if CLIENT.auths_by_tag['auth:bank_matls'] not in CLIENT.tokens_by_auth:\n",
    "#     setup = {\n",
    "#         'meta': {\n",
    "#             'name': 'Authenticated User Access Token',\n",
    "#             'domain': DOMAIN,\n",
    "#             'auth_id': CLIENT.auths_by_tag['auth:bank_matls']\n",
    "#         },\n",
    "#         'token': {}\n",
    "#     }\n",
    "#     token = CLIENT.create_token(setup)\n",
    "#     print(f\"Created Auth Token {token['meta']['name']} with id {token['id']}\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create APIs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bulk APIs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# CLIENT.auths_by_tag['auth:bank_matls'] = \"agpzfnZpYXRlc3RzchoLEg1TZXJ2aWNlQ29uZmlnGICAmMiwnOEIDA\"\n",
    "tag = \"bulk:accounts\"\n",
    "id_str = create_call_if_needed(tag)\n",
    "conditions = {\n",
    "    \"conditions\": [\n",
    "        {\n",
    "          \"source\": \"RESPONSE_BODY\", \n",
    "          \"test_result_on_true\": None, \n",
    "          \"val\": \"\", \n",
    "          \"variable_path\": \"Data.Account[0].AccountId\", \n",
    "          \"variable_name\": \"ACCOUNT_ID\", \n",
    "          \"test_result_on_false\": \"CONTENT_ERROR\", \n",
    "          \"condition\": \"EXISTS\"\n",
    "        },\n",
    "      ]\n",
    "}\n",
    "CLIENT.set_call_conditions(id_str, conditions)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:balances\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:transactions\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:beneficiaries\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:directdebits\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:standingorders\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:products\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:offers\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:party\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:scheduledpayments\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"bulk:statements\"\n",
    "id_str = create_call_if_needed(tag)\n",
    "conditions = {\n",
    "    \"conditions\": [\n",
    "        {\n",
    "          \"source\": \"RESPONSE_BODY\", \n",
    "          \"test_result_on_true\": None, \n",
    "          \"val\": \"\", \n",
    "          \"variable_path\": \"Data.Statement[0].StatementId\", \n",
    "          \"variable_name\": \"STATEMENT_ID\", \n",
    "          \"test_result_on_false\": \"CONTENT_ERROR\", \n",
    "          \"condition\": \"EXISTS\"\n",
    "        },\n",
    "      ]\n",
    "}\n",
    "CLIENT.set_call_conditions(id_str, conditions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Account APIs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:account\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:balance\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:transactions\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:beneficiaries\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:directdebits\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:standingorders\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:product\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:offers\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:party\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:scheduledpayments\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:statements\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:statement\"\n",
    "id_str = create_call_if_needed(tag)\n",
    "conditions = {\n",
    "    \"conditions\": [\n",
    "        {\n",
    "          \"source\": \"RESPONSE_BODY\", \n",
    "          \"test_result_on_true\": None, \n",
    "          \"val\": \"\", \n",
    "          \"variable_path\": \"Data.Statement[0].StatementId\", \n",
    "          \"variable_name\": \"STATEMENT_ID\", \n",
    "          \"test_result_on_false\": \"CONTENT_ERROR\", \n",
    "          \"condition\": \"EXISTS\"\n",
    "        },\n",
    "      ]\n",
    "}\n",
    "CLIENT.set_call_conditions(id_str, conditions)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:statement_file\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "tag = \"account:statement_transactions\"\n",
    "create_call_if_needed(tag)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Workflow for Account APIs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tag = 'banks:3.1:account:apis'\n",
    "if tag not in CLIENT.workflows_by_tag:\n",
    "    call_tags = [\n",
    "        \"banks:3.1:bulk:accounts\",    \n",
    "        \"banks:3.1:account:account\",\n",
    "        \"banks:3.1:account:balance\",\n",
    "        \"banks:3.1:account:transactions\",\n",
    "        \"banks:3.1:account:beneficiaries\",\n",
    "        \"banks:3.1:account:directdebits\",\n",
    "        \"banks:3.1:account:standingorders\",\n",
    "        \"banks:3.1:account:product\",\n",
    "        \"banks:3.1:account:offers\",\n",
    "        \"banks:3.1:account:party\",\n",
    "        \"banks:3.1:account:scheduledpayments\",\n",
    "        \"banks:3.1:account:statement\",\n",
    "        \"banks:3.1:account:statements\",\n",
    "        \"banks:3.1:account:statement_file\",\n",
    "        \"banks:3.1:account:statement_transactions\",\n",
    "    ]\n",
    "    for t in call_tags:\n",
    "        assert t in CLIENT.calls_by_tag, f\"API {t} does not exist\"\n",
    "\n",
    "    setup = {\n",
    "      \"meta\": {\n",
    "        \"name\": \"v3.1: Account APIs\", \n",
    "        \"workspace\": \"global\", \n",
    "        \"tags\": [tag], \n",
    "      }, \n",
    "      \"workflow\": {\n",
    "        \"handle_cookies\": False,\n",
    "        \"stop_on_failure\": False,\n",
    "        \"call_ids\": [CLIENT.calls_by_tag[t] for t in call_tags]\n",
    "      }\n",
    "    }\n",
    "    workflow = CLIENT.create_workflow(setup)\n",
    "    print(f\"Created Workflow {workflow['meta']['name']} with id {workflow['id']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}