API Description

Split API description

The backend server is hosted from a CherryPy server. Both webpages and API requests are made over HTTP.

All API calls are POST requests. Both send and return parameters are contained in the payload body in JSON format. Bill refers to an entire payment split between many people, whereas payment refers to an individual payment from one person as part of the bill.

For API development and testing, a collection of requests for Postman is available below.

For more information on what Postman is and how to use it with Split, click here.

Example js API invocation:

var theUrl = "/api/some_api";
xhttp.open("POST", theUrl, true);
xhttp.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhttp.onreadystatechange = function() { //return callback       
  if(xhttp.readyState === 4 && xhttp.status === 200)
  {
     let response = JSON.parse(xhttp.responseText);
     let some_data = response.some_data;
  }
}
xhttp.send(JSON.stringify({ "email": "hello@user.com", "response": { "name": "Tester" } })); 

Account endpoints

/api/account/register:

Purpose: Sends a request for a new account to be created

Send Parameters:

Parameter Name	Format	Description
username	string	Name used for login
password	string	Password used for login, preferably hashed (we need to decide whether client or server hashes)

Return Parameters:

Parameter Name	Format	Description
success	bool	true if registered sucessfully, false otherwise
message (optional)	string	e.g. "Account with this name already exists"

/api/account/login:

Purpose: Sends a request to log in to a specific user account

Send Parameters:

Parameter Name	Format	Description
username	string	Name used for login
password	string	Password used for login

Return Parameters:

Parameter Name	Format	Description
success	bool	true if logged in sucessfully, false otherwise
message (optional)	string	e.g. "Password incorrect"

/api/account/logout:

Purpose: Sends a request to log out of a specific user account

Send Parameters:

Parameter Name	Format	Description

Return Parameters:

Parameter Name	Format	Description
success	bool	true if logged out sucessfully, false otherwise
message (optional)	string	e.g. "Logout unsuccessful"

Bill endpoints

/api/bill_data/get_bills:

Purpose: Requests all bills belonging to this account.

In the future, may be good to consider when the user has a lot of bills (such as returning only the most recent bills or only outstanding bills and giving them the ability to get more or search).

Send Parameters:

Parameter Name	Format	Description
sort_field	string	The field this is sorted by. It will be "name" to sort by name, "amount" for total bill cost, and "created time" to sort by the time
sort_order	string	The sorting order, either "asc" for ascending or "desc" for descending
is_paid	string	Filter by whether or not a bill has been paid. "paid", "unpaid", or "either"
payer	string	Filter by the person/people who owe someone money
payee	string	filter by the person who is owed money
page_number	integer	The page number required

Return Parameters:

Parameter Name	Format	Description
bills	list of bill JSONs	all bills the user has in format shown below
message (optional)	string	error message if applicable (e.g. not signed in)
num_of_bills	int	Number of bills that meet the criteria

Bill Summary format:

Parameter Name	Format	Description
bill_id	integer	unique identifier for this bill
timestamp	unix epoch timestamp	time of bill creation
title	string	user-defined name of this bill (e.g. maccas run)
total	float	the value of the entire bill
payments	list of payment JSONs	each individual payment that makes up this bill, format described below

Individual Payment Format:

Parameter Name	Format	Description
payment_id	integer	unique identifier for this payment
to	string	name of the person owed money
from	string	name of the person owing money
amount	float	value of the money this person owes
is_paid	bool	whether this payment is complete

/api/bill_exec/create_bill:

Purpose: Requests the creation of a bill

Send Parameters:

Parameter Name	Format	Description
title	string	user-defined name of this bill (e.g. maccas run)
payer	string	name of the person who fronted the bill
total	double	total amount of bill
outstanding_payments	lists of outstanding_payments JSON (see below)	a (string, int) pair relating a person's name to the amount of money they owe

Individual outstanding_payment Format:

Parameter Name	Format	Description
person	string	name of person
amount	double	amount of money outstanding

Return Parameters:

Parameter Name	Format	Description
success	bool	true if payment made, false otherwise
message (optional)	string	error message if applicable (e.g. not signed in)

/api/bill_exec/del_bill:

Purpose: Deletes a bill from the database

Send Parameters:

Parameter Name	Format	Description
bill_id	integer	unique identifier for the bill

Return Parameters:

Parameter Name	Format	Description
message (optional)	string	error message if applicable (e.g. not signed in)

/api/pay_exec/make_payment:

Purpose: Clears an individual payment from a bill

Send Parameters:

Parameter Name	Format	Description
payment_id	integer	unique identifier for this payment
is_paid	boolean	value to set the payment to (paid or unpaid)

Return Parameters:

Parameter Name	Format	Description
success	bool	true if payment made, false otherwise
message (optional)	string	error message if applicable (e.g. not signed in)