Introduction

Athena Alpha is built in three separate parts: Client, Server and Database

  1. The Client side is built using React (JavaScript) and is the presentation layer for the user. It only performs logic to do with displaying the data correctly and preparing new data to be sent to the Server REST API for processing
  2. The Server side is built using PHP and has its own RESTful API end points that the anyone can interact with and use to build their own front end client, either for the desktop, mobile or other interfaces
  3. The Database is built with MariaDB and communicates only with the Server side via PHP PDO

All API end points require HTTPS encryption. All API end points (besides the /auth/login end point) also require the user to be logged in and their valid JWT sent via the Authorization Bearer header.

Depending on what activity you wish to perform will change the HTTP Method you’ll send.

ActivityHTTP MethodData Transfer Method
Get DataGETSent in the URL of the request
Add New DataPOSTSent in a JSON Object in the request body
Update DataPATCHSent in a JSON Object in the request body
Delete DataDELETESent in the URL of the request

Returned HTTP Status Codes

Athena Alpha adheres to strict industry standard HTTP Status Codes

  • GET = 200 (204 for no results found)
  • POST = 201
  • PATCH = 204
  • DELETE = 204

All other returned codes are 4xx and include a JSON Object containing:

  • Error – API specific error code
  • Message – User displayable error message
  • Detail – More detailed overview of the error for Developers
[
    {
        "error": 10,
        "message": "Login failed: Invalid username or password",
        "detail": "Either the Username or Password were incorrect or did not validate properly"
    }
]

Users

Users is made of two databases, user and user_setting that relate to all User data including login, password hash, language etc

Database

User

ParameterDescription
idInteger: Unique identifier
loginString: Unique login
hashString: Argon2id hashed user password
typeInteger: User account type Administrator (1), Standard User (2)

User Setting

ParameterDescription
idInteger: Unique identifier
user_idInteger: Unique User identifier
settingString: One of ‘language’, ‘currency’, avatar’, ‘countdown_1_plan_id’, ‘countdown_2_plan_id’, ‘countdown_3_plan_id’, ‘financial_year’, ‘password_reset_request’
valueString: Setting value

API

* means this parameter is required

GET /usersMust be Administrator to request specific users via ‘id’, ‘login’ , otherwise users own information is returned
limitInteger: Maximum 100
GET /users/settings/
settingString: One of ‘language’, ‘currency’, avatar’, ‘countdown_1_plan_id’, ‘countdown_2_plan_id’, ‘countdown_3_plan_id’, ‘financial_year’, ‘password_reset_request’
POST /auth/register/
login *String: User login
pass *String: User password
confirm_pass *String: User password (must match ‘pass’)
PATCH /users/Must be Administrator to update any user using the id variable
id *Integer: id of data to be updated (Administrator use only, not required if updating users own data)
Column to be updated *Must provide at least 1 parameter to update
PATCH /users/settings/
settingString: One of ‘language’, ‘currency’, avatar’, ‘countdown_1_plan_id’, ‘countdown_2_plan_id’, ‘countdown_3_plan_id’, ‘financial_year’, ‘password_reset_request’
valueString: Value of the settings you’re wanting to update
DELETE /users/delete-account/Can only be used to delete the currently logged in user
none

Example:
https://athena-alpha.com/api/v1/users/?id=1

[
    {
        "id": 1,
        "login": "Athena",
        "type": 1,
        "settings": {
            "countdown_1_plan_id": "5",
            "countdown_2_plan_id": "8",
            "countdown_3_plan_id": "31",
            "currency": "AUD",
            "language": "en",
            "avatar": "avatar_1.png",
            "financial_year": "julToJun"
        }
    }
]

Sessions

Sessions relates to all User Session data including user id, the session expire time and JWT

Database

ParameterDescription
idInteger: Unique identifier
user_idInteger: Unique User identifier
expire_timeInteger: Date time of when the session expires, expressed in EPOC time
refresh_tokenString: Current JWT refresh token

API

* means this parameter is required

GET /users/sessions/Returns all tracked sessions for the currently logged in user
none
DELETE /users/sessions/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/sessions/

[
    {
        "id": 3,
        "expire_time": 1665124681
    },
    {
        "id": 6,
        "expire_time": 1682860055
    }
]

Plans

Plans relate to all Strategic Planning data including Objectives, Goals and Action Items

Database

ParameterDescription
idInteger: Unique identifier
master_idInteger: id of the master Plan, Objective = id, Goal = Objective_id, Action Item = Goal_id
author_idInteger: id of the author matched to the Users database
shared_with_idString: Comma separated list of user id’s that can view
pillarString: One of Health, Finance, Purpose, Security
moduleString: Investing, Travel, French etc
typeInteger: One of Objective (1), Goal (2), Action Item (3)
descriptionString: Brief description of the plan
notesString: Extensive notes for the plan
start_date_timeDate Time: 2021-12-01 00:00:00 UTC
end_date_timeDate Time: 2021-12-01 00:00:00 UTC
target_startFloat: Target starting point of the plan
target_finishFloat: Target finish point of the plan
target_currentFloat: Target current point of the plan
target_unitsInteger: One of the below
Value: 1 – Number (1,000)
Value: 2 – Number (1,000.2)
Value: 3 – Number (1,000.23)
Value: 4 – Dollar ($1,000)
Value: 5 – Dollar ($1,000.23)
Value: 6 – Euro (€1,000)
Value: 7 – Euro (€1,000.23)
Value: 8 – Bitcoin (₿1,000)
Value: 9 – Bitcoin (₿1,000.23)
Value: 10 – Ethereum (Ξ1,000)
Value: 11 – Ethereum (Ξ1,000.23)
Value: 12 – Celsius (100°C)
Value: 13 – Grams (1,000 g)
Value: 14 – Kilograms (1,000 kg)
Value: 15 – Meters (1,000 m)
Value: 16 – Kilometres (1,000 km)
Value: 17 – Millilitres (100 ml)
Value: 18 – Litres (100 L)
Value: 19 – Percent (100%)
Value: 20 – Hours (100 hrs)
Value: 21 – Days (100 days)
Value: 22 – Months (100 mths)
Value: 23 – Years (100 yrs)
target_auto_typeString: Can be any stored Resource Type (eg. finance), Sub Module Type (eg. liability), Module Type (asset)
target_auto_levelInteger: One of Manual (0), Module (1) / Sub Module (2) / Resource (3)
target_auto_idString: Can be any stored Resource ID (eg. 57), Sub Module Value (eg. sleep), Module Value (eg. finance)
priorityInteger: Low Priority (1), Normal Priority (2), High Priority (3), Top Priority (4)
statusInteger: Draft (1), Not Started (2), In Progress (3), Missed (4), Cancelled (5), Complete (6)

API

* means this parameter is required

GET /plans/Can request specific plans via: id, master_id, author_id, pillar, module, type, priority, status
order_byString: One of ‘pillar’, ‘module’, ‘description’, ‘start_date_time’, ‘end_date_time’, ‘priority’, ‘status’, ‘type’
limitInteger: Maximum 100
POST /plans/
All columns *Except pillar and module when creating a Goal or Action Item plan
PATCH /plans/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /plans/Must be the author of supplied id to delete a plan
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/plans/?id=10

[
    {
        "id": 10,
        "master_id": 0,
        "author_id": [
            {
                "id": 1,
                "login": "Athena",
                "avatar": "avatar_1.png"
            }
        ],
        "shared_with_id": [
            {
                "id": 2,
                "login": "Alice",
                "avatar": "avatar_2.png"
            }
        ],
        "pillar": "finance",
        "module": "asset",
        "type": 1,
        "description": "Have a net worth of $1,000,000 by 50",
        "notes": "",
        "start_date_time": "2016-06-30 14:00:00",
        "end_date_time": "2040-08-19 14:00:00",
        "target_start": 0,
        "target_finish": 1000000,
        "target_current": 50000,
        "target_units": 4,
        "priority": 2,
        "status": 3
    }
]

Language – Words

Words relates to all the Word data for the Language module

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
native_wordString: The word in the users native spoken language
foreign_wordString: The word in the users chosen foreign language

API

* means this parameter is required

GET /languages/words/
idInteger: Unique identifier
randomInteger: One of Yes (1) or No (0)
order_byString: One of ‘native_word’, ‘foreign_word’
limitInteger: Maximum 100
POST /languages/words/
All columns *
PATCH /languages/words/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /languages/words/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/languages/words/?random=1&limit=3

[
    {
        "id": 161,
        "native_word": "our",
        "foreign_word": "notre"
    },
    {
        "id": 708,
        "native_word": "speed",
        "foreign_word": "vitesse"
    },
    {
        "id": 651,
        "native_word": "wrote",
        "foreign_word": "\u00e9crit"
    }
]

Language – Phrases

Phrases relates to all the Phrases data for the Language module

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
native_phraseString: The phrase in the users native spoken language
foreign_phraseString: The phrase in the users chosen foreign language

API

* means this parameter is required

GET /languages/phrases/
idInteger: Unique identifier
randomInteger: One of Yes (1) or No (0)
order_byString: One of ‘native_phrase’, ‘foreign_phrase’
limitInteger: Maximum 100
POST /languages/phrases/
All columns *
PATCH /languages/phrases/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /languages/phrases/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/languages/phrase/?random=1&limit=3

[
    {
        "id": 144,
        "native_phrase": "Have a good nights sleep",
        "foreign_phrase": "Bonne nuit"
    },
    {
        "id": 147,
        "native_phrase": "I'm still learning French",
        "foreign_phrase": "J'apprends toujours le fran\u00e7ais"
    },
    {
        "id": 127,
        "native_phrase": "We're meeting there at 2pm",
        "foreign_phrase": "On se retrouve l\u00e0-bas \u00e0 14h"
    }
]

Language – Conjugations

Conjugations relates to all the Conjugations data for the Language module

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
verbString: The verb being conjugated in the foreign language
definitionString: Translation of the verb being conjugated in the native spoken language
present_1String: 1st present tense conjugation of the verb
present_2String: 2nd present tense conjugation of the verb
present_3String: 3rd present tense conjugation of the verb
present_4String: 4th present tense conjugation of the verb
present_5String: 5th present tense conjugation of the verb
present_6String: 6th present tense conjugation of the verb
present_negation_1String: 1st present negative tense conjugation of the verb
present_negation_2String: 2nd present negative tense conjugation of the verb
present_negation_3String: 3rd present negative tense conjugation of the verb
present_negation_4String: 4th present negative tense conjugation of the verb
present_negation_5String: 5th present negative tense conjugation of the verb
present_negation_6String: 6th present negative tense conjugation of the verb

API

* means this parameter is required

GET /languages/conjugations/You can request either a random set of conjugations or a specific one using its id or verb
idInteger: Unique identifier
verbString: The verb being conjugated in the foreign language
randomInteger: One of Yes (1) or No (0)
limitInteger: Maximum 100
POST /languages/conjugations/
All columns *
PATCH /languages/conjugations/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /languages/conjugations/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/languages/conjugations/?limit=1&random=1

[
    {
        "id": 57,
        "author_id": 1,
        "verb": "contenir",
        "definition": "contains, holding, store",
        "present_1": "je contiens",
        "present_2": "tu contiens",
        "present_3": "il contient",
        "present_4": "nous contenons",
        "present_5": "vous contenez",
        "present_6": "ils contiennent",
        "present_negation_1": "je ne contiens pas",
        "present_negation_2": "tu ne contiens pas",
        "present_negation_3": "il ne contient pas",
        "present_negation_4": "nous ne contenons pas",
        "present_negation_5": "vous ne contenez pas",
        "present_negation_6": "ils ne contiennent pas"
    }
]

Language – Grammar

Grammar relates to all the Grammar data for the Language module

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
ruleString: The grammar rule, described in the native spoken language
example_1_nativeString: 1st grammar rule example in the native spoken language
example_1_foreignString: 1st grammar rule example in the foreign language
example_2_nativeString: 2nd grammar rule example in the native spoken language
example_2_foreignString: 2nd grammar rule example in the foreign language
example_3_nativeString: 3rd grammar rule example in the native spoken language
example_3_foreignString: 3rd grammar rule example in the foreign language

API

* means this parameter is required

GET /languages/grammar/You can request either a random set of grammar rules or a specific one using its id
idInteger: Unique identifier
randomInteger: One of Yes (1) or No (0)
limitInteger: Maximum 100
POST /languages/grammar/
All columns *Except id, author_id
PATCH /languages/grammar/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /languages/grammar/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/languages/grammar/?random=1&limit=2

[
    {
        "id": 9,
        "author_id": 1,
        "rule": "If a verb begins with a vowel, be sure to change je to j'. We see this happen with j'ai, which means I have.",
        "example_1_native": "I have a passport.",
        "example_1_foreign": "J'ai un passeport.",
        "example_2_native": "",
        "example_2_foreign": "",
        "example_3_native": "",
        "example_3_foreign": ""
    },
    {
        "id": 98,
        "author_id": 1,
        "rule": "We've seen how to use c'est to talk about how things are right now. Use c'\u00e9tait to talk about how things were in the past!",
        "example_1_native": "It was the good life",
        "example_1_foreign": "C'\u00e9tait la belle vie",
        "example_2_native": "",
        "example_2_foreign": "",
        "example_3_native": "",
        "example_3_foreign": ""
    },
]

Currency

Currency relates to all the officially supported Currencies that Athena Alpha supports. This database is only accessed by the Server side and has no public facing API end points

Database

ParameterDescription
idInteger: Unique identifier
codeString: Three letter currency code (eg. USD)
descriptionString: Full official name of currency (eg. Bitcoin)
symbolString: Symbol for currency (eg. $)
typeString: One of ‘fiat’, ‘crypto’

Finance – Resources

Resources relates to all the Resource data for the Finance module including Cash Flow, Assets and Liabilities

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
shared_with_idString: Comma separated string listing all User unique identifiers that are able to see this resource
descriptionString: Brief user description of the resource
typeString: One of ‘cash-flow’, ‘liability’, ‘asset’
tagString: One of ‘salary’, ‘dividends’, ‘business-income’, ‘rental-income’, ‘interest’, ‘mortgage’, ‘business-debt’, ‘car-debt’, ‘student-debt’, ‘credit-card-debt’, ‘stocks’, ‘retirement’, ‘real-estate’, ‘currency’, ‘crypto’
tickerString:
Tag = ‘mortgage’: The interest rate of the mortgage in percent (eg. 2.5 for 2.5%)
Tag = All others: Any ticker symbol from Yahoo! Finance, Coin Gecko or one of the supported Athena Alpha currencies (eg USD)
repayment_amountFloat:
Tag = ‘mortgage’: The repayment amount chosen by the user
Type = ‘cash-flow’: The profit target amount chosen by the user
repayment_frequencyString: One of ‘weekly’, ‘fortnightly’, ‘monthly’, ‘quarterly’, ‘yearly’
Tag = ‘mortgage’: The repayment frequency chosen by the user
Type = ‘cash-flow’: The profit target frequency chosen by the user

API

* means this parameter is required

GET /finances/resources/You can request either all resources for the user or only resources that match any parameter
order_byInteger: One of ‘description’, ‘type’, ‘tag’, ‘ticker’, with options of ‘ASC’ or ‘DESC’
limitInteger: Maximum 100
POST /finances/resources/
All columns *Except id, author_id
shared_with_id: Sent as an array of user_id’s
If the resource being created is of type = ‘liability’ or a tag = ‘real-estate’ you must also submit:
initial_price: Initial price of the liability or real-estate asset
initial_price_date: Initial purchase date of the liability or real-estate asset
currency_id: Supported Athena Alpha currency id of the liability or real-estate asset
PATCH /finances/resources/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /finances/resources/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/finances/resources/?type=stocks&order_by=description%20ASC

[
    {
        "id": 78,
        "author_id": [
            {
                "id": 1,
                "login": "Athena",
                "avatar": "avatar_1.png"
            }
        ],
        "shared_with_id": "",
        "description": "Failbook Stocks",
        "type": "asset",
        "tag": "stocks",
        "ticker": "FB",
        "repayment_amount": 0,
        "repayment_frequency": "fortnightly"
    },
    {
        "id": 80,
        "author_id": [
            {
                "id": 1,
                "login": "Athena",
                "avatar": "avatar_1.png"
            }
        ],
        "shared_with_id": "",
        "description": "Google Stock",
        "type": "asset",
        "tag": "stocks",
        "ticker": "GOOG",
        "repayment_amount": 0,
        "repayment_frequency": "fortnightly"
    },
]

Finance – Transactions

Transactions relates to all the Transaction data for the Finance module including Cash Flow, Assets and Liabilities

Database

ParameterDescription
idInteger: Unique identifier
author_idInteger: Unique User identifier
resource_idInteger: Unique Resource identifier
dateDate Time: 2021-12-01 00:00:00 UTC
descriptionString: Brief user description of the transaction
unit_countDouble: Number of units of the thing being transacted (eg. 10 shares)
unit_priceDouble: Price of a single unit of the thing being transacted (eg. 1 share = $400)
currency_idInteger: Supported Athena Alpha currency id of the item being transacted (eg. USD = 1)

API

* means this parameter is required

GET /finances/transactions/You can request either all transactions for the user or only resources that match any parameter
order_byInteger: One of ‘resource_id’, ‘date’, ‘description’, ‘unit_count’, ‘unit_price’, with options of ‘ASC’ or ‘DESC’
limitInteger: Maximum 100
POST /finances/transactions/
All columns *Except id, author_id
PATCH /finances/transactions/
id *Integer: id of data to be updated
Column to be updated *Must provide at least 1 parameter to update
DELETE /finances/transactions/
id *Integer: id of data to be deleted

Example:
https://athena-alpha.com/api/v1/finances/transactions/?resource_id=57&limit=100&order_by=date%20DESC

[
    {
        "id": 1745,
        "author_id": 1,
        "resource_id": [
            {
                "id": 57,
                "description": "Tesla Stock",
                "type": "asset",
                "tag": "stocks",
                "ticker": "TSLA"
            }
        ],
        "date": "2020-08-11 10:00:00",
        "description": "5 to 1 Share Split",
        "unit_count": 400,
        "unit_price": 0.01,
        "currency_id": 3,
        "unit_price_in_user_currency": 0.01,
        "no_currency_rates_data_flag": false,
        "live_price": 865.65,
        "live_value": 489205.9903927663,
        "CAGR": 83898.55357159859
    },
    {
        "id": 1258,
        "author_id": 1,
        "resource_id": [
            {
                "id": 57,
                "description": "Tesla Stock",
                "type": "asset",
                "tag": "stocks",
                "ticker": "TSLA"
            }
        ],
        "date": "2017-03-27 00:00:00",
        "description": "Tesla Stock Purchase",
        "unit_count": 100,
        "unit_price": 250,
        "currency_id": 3,
        "unit_price_in_user_currency": 250,
        "no_currency_rates_data_flag": false,
        "live_price": 865.65,
        "live_value": 122301.49759819158,
        "CAGR": 36.371630655947484
    }
]