[REST API] Questions and improvements
Hello!
My name is Bohdan and currently I'm working on making application communicate with SQL-Ledger by REST API using HTTP requests with JSON payloads.
During my initial attempts to set up SQL-Ledger with REST API (based on branch "326_rest_api" from "ledger123/runmyaccounts" repository), i've managed to address SQL-Ledger via HTTP.
After some testing and investigation, i've gathered some info/questions that I'd like to discuss.
Please, see listing below:
1) Authentication:
a. api_key must not be constant in case of public access.
(currently api_key is stored as constant in ‘defaults’ table)
* not RMA case
b. api_key must be passed to server as header.
(now passed as header in case of POST and as query parameter in case of GET)
2) Error handling:
a. Error responses must be of the same content-type as usual responses:
If client is expecting to get JSON, but error occurred during processing, JSON with error details should be returned.
b. HTTP request status must always represent actual result (regardless of problem was on client side - 4XX code or server side 5XX code):
![[image]](images/uploaded/20230427061404644a12aced971.png)
3) Response payload:
a. When requesting an entity OR list of entities, but they do not exist – empty response with “404 Not Found” code must be returned.
(screenshot - get transaction by id case; the same applies to get transaction list where empty array with 200 OK is returned in current version):
![[image]](images/uploaded/20230427061541644a130da4735.png)
b. Response payload of POST, PUT, PATCH requests must be the same as for GET:
(non-bulk case described)
GET by id – returns entity as JSON
POST / PUT / PATCH – creates / replaces / updates entity and returns it as JSON
Code for
GET – 200 OK
POST – 200 OK / 201 Created
PUT – 200 OK / 201 Created
PATCH – 200 OK
In current version POST gl transactions responses with:
{ “code”: 300, message: “7649” } 200 OK
4)Ambiguity:
Entities JSON representations must not create any ambiguity when it comes to understanding of attributes. Currently POST of gl transaction requires both “accno” and “chart_id” to be sent despite to the fact that they are pointing to the same chart of accounts. The same applies to such attribute pairs as “department_id” + “department”, “project_id” + “projectnumber”.
Best practice would be to keep only identifier as required field for POST request, BUT in case of need to render names on client side – they can be wrapped as a ObjectRef’s:
{
…,
“chart”: {
“chart_id”: number (required)
“accno”: string (optional)
“description”: string (optional)
…
},
…
}
Also, would be great to have descriptors for request/response payloads to clarify them for API consumers.
Descriptors should explain
a. JSON example
b. Value types for attributes
c. Mandatory/non-mandatory attributes
5) Actual issues OR lack of understanding:
During testing of API behavior (mostly POST gl transaction) I found out that
a. ‘department’, ‘project’ and ‘currency’ are not set to new transaction even if they were sent
b. ‘exchange rate’ is always set to 1 even if default currency is used
6) improvedgl.pl:
a. has simplified request payload, has better response (tested on https://ledgeri.mnapk.com/login.pl)
b. Is it possible to use it instead?
*** end of listing
Thanks in advance for your attention!