WIP api extension specs per 20200810

spec/012_multitoken_platform_api_extension.md

@@ -0,0 +1,70 @@
+# API EXTENSIONS FOR EXTERNALLY CREATED BLOCKCHAIN RESOURCES
+
+At time of writing, apis are registered under `/api/v2`. This will change.
+
+## NOMENCLATURE
+
+Values enclosed with `<>` are _required_.
+
+Values enclosed with `[]` means _optional_.
+
+No enclosure means _literal_.
+
+## CHANGED METHODS
+
+Endpoints _modified_ are found under /api/v1/
+
+Changes will be submitted upstream.
+
+### `/api/v1/organisation`
+
+### **POST**
+
+One item is added to data payload:
+
+```
+{
+	account_address: [address],
+}
+```
+
+If specified, the organisation will be bound to the specified blockchain account, and _will not_ create a new account on instantiation.
+
+## ADDED METHODS
+
+Endpoints _added_ are found under /api/ext/
+
+### `/api/ext/exchange/register`
+
+#### **POST**
+
+Creates a new entry in `exchange_contract` table in database.
+
+Requires token addresses to be registered in advance on `/api/v1/token/`
+
+Request payload:
+```
+{
+	reserve_address: <address>,
+	token_address: <address>,
+	converter_address: <address>,
+	registry_address: <address>,
+	connector_weight: <uint>,
+}
+```
+
+Response payload on success:
+```
+{
+	message: 'Exchange added',
+	data: {
+		exchange: (exchange schema dump, TODO specify)
+	}
+}
+```
+
+Returns:
+```
+201 - exchange record created
+400 - token addresses not known to platform
+```

spec/013_locations_api_extension.md

@@ -0,0 +1,102 @@
+# API EXTENSIONS FOR MANIPULATING LOCATIONS RECORDS
+
+## NOMENCLATURE
+
+Values enclosed with `<>` are _required_.
+
+Values enclosed with `[]` means _optional_.
+
+No enclosure means _literal_.
+
+## ADDED METHODS
+
+Endpoints _added_ are found under /api/ext/
+
+### `/api/ext/geolocation/`
+
+#### **POST**
+
+Adds a location entry to the database
+
+Request payload:
+```
+{
+	common_name: <string>,
+	latitude: <float>,
+	longitude: <float>,
+	parent_id: [uint],
+}
+
+```
+
+`parent_id` is the location table id of the location record for the greater area encapsulating the location being registered.
+
+### `/api/ext/geolocation/<path_string>/`
+
+#### **GET**
+
+Retrieves a location record based on the given `path_string`. Every part of the given path string must match the value in the location hierarchy. A path string must have minimum one part.
+
+Example, given database has `foo/bar` and `foo/baz`: A search of `foo/bar` will only match `foo/bar`. A search of `foo` will match both `foo/bar` and `foo/baz`.
+
+Response payload:
+
+```
+{
+	id: <uint>,
+	common_name: <string>,
+	path: <string>,
+	latitude: <float>,
+	longitude: <float>,
+}
+
+```
+
+`common_name` is the location leaf name.
+
+`path` is the full hierarchical path string.
+
+### `/api/ext/geolocation/<ext_type>/<ext_id>/`
+
+
+#### **GET**
+
+Queries the `location_external` table for a matching value, and returns the `location` object associated with it. 
+
+Currently only `OSM` is supported as `ext_type`. The value given matches a `place_id` entry in the external table.
+
+Data format returned the same as `GET /api/ext/geolocation/<path_string>/`
+
+### `/api/ext/user/<user_id>/geolocation/`
+
+#### **PUT**
+
+Sets the location of the affected user
+
+Data payload:
+
+```
+{
+	location_id: <uint>
+}
+```
+
+#### **GET**
+
+Retrieves full objects for the hierarchical path of the user location.
+
+Response payload:
+
+```
+{
+	user_id: user_id,
+	location: [
+		{
+			common_name: <string>,
+			longitude: <float>,
+			latitude: <float>,
+		},
+		...
+	],
+}
+```

spec/015_accounts_api_extension.md

@@ -0,0 +1,80 @@
+# API EXTENSIONS FOR INDEPENDENT TRANSFER ACCOUNTS
+
+At time of writing, apis are registered under `/api/v2`. This will change.
+
+## NOMENCLATURE
+
+Values enclosed with `<>` are _required_.
+
+Values enclosed with `[]` means _optional_.
+
+No enclosure means _literal_.
+
+## ADDED METHODS
+
+Endpoints _added_ are found under /api/ext/
+
+### `/api/ext/transfer_account/register/`
+
+#### **POST**
+
+Create a new transfer_account bound to an organisation.
+
+Request payload:
+```
+{
+	address: <address>,
+	organisation_id: <uint>,
+}
+```
+
+Response payload on success:
+```
+{
+	message: 'Created',
+	data: {
+		id: <uint>
+	},
+}
+```
+
+`id` is the id of the newly created transfer account
+
+Returns:
+```
+201 - transfer account is added
+400 - address or organisation data invalid
+404 - organisation not found
+```
+
+### `/api/ext/user/`
+
+#### **POST**
+
+Add a new user without transfer account. The user will be associated with the organisation in the API session context.
+
+Request payload:
+```
+{
+	phone: <string>,
+	first_name: <string>,
+	last_name: <string>,
+}
+```
+
+Response payload on success:
+```
+{
+	data: {
+		id: <uint>
+	},	
+}
+```
+
+`id` is the id of the newly created user.
+
+Returns:
+```
+201 - user created
+400 - organisation context missing
+```