Prerequisite: install GoLang locally install PostgreSQL server locally if changed from default - add variables for DB to .envrc file
This is a simple CRUD backend service which attaches to the PostgreSQL DB and wraps simple operations including:
- DB modeling and initialization (on startup)
- Create operation (add row to table in DB, from given data)
- Read operation (retrieve 1 row from database, from given ID)
- List operation (retrieve X rows from database, from given metadata)
-
- List operation with relationships
- Update operation (update 1 row in database, from given data)
- Delete operation (soft-delete 1 row from database, from given ID)
Also, this service offers authentication services:
- Create access/refresh token pairs
- Use tokens in pairs to login, set through headers
- Log the user out, if needed (destroy tokens)
see Response section for universal response
- DB modeling and initialization (on startup)
-> First, to retrieve all libs, run in root folder "go mod tidy" -> Run the service from /cmd/server using "go run main.go" (thats it, the service should be available for instance on https://localhost:8000 - this is the assumed URL from now on)
- Create operation (add row to table in DB, from given data) see Relations section for relation definition
-> Execute POST request: Address: https://localhost:8000/create Body:
{
"entity": "category", //required for entity determination
"data": { //contains values for all fields
"name": "testCategory",
"active": true,
"text": "testText"
//...etc. (see Entities section for model specification)
}
}
entities : "product": "review": "order": "user": "discount": "category": "sales_channel "cart"
- Read operation (retrieve 1 row from database, from given ID)
-> Execute POST request: Address: https://localhost:8000/read Body:
{
"entity": "category", //required for entity determination
"data": {
"id": 3 //specify ID of entity to be read
}
}
- List operation (retrieve X rows from database, from given metadata)
-> Execute POST request: Address: https://localhost:8000/list Body:
{
"entity": "category", //required for entity determination
"metadata": {
"filter": {
"must": [ //hard filters, connected with AND logical operator (all apply)
{
"key": "name",
"value": "testCategory",
"type": "eq", //see Filters section for filter types
},
{
"key": "active",
"value": "true",
"type": "eq", //see Filters section for filter types
},
],
"should": [ //soft filters, connected with OR logical operator (any one applies)
// same as above
]
},
"orderBy": { //designate ordering of data in response
"key": "id",
"type": "desc", //asc - ascending, desc - descending
},
"fields": [ //specify response fields
//if empty retrieves all
//will always retrieve non null fields: 'ID, CreatedAt, UpdatedAt, DeletedAt'
"id",
"name"
],
"limit": 10, //specify limit for DB retrieval (default 10, max 100)
"page": 1 //specify page for DB retrieval (default 0)
}
}
-
- List operation with relationships (many 2 many relationships) -> Add relationships in list requests in order to retrieve related data, as well as the primary entities. Relationship names match the plural names of fields inside the data models. There are 3 ways of retrieving relation data:
Technical Documentation for Connecting with Xentral
- POST Import orders request https://ORGANISATION-ID.xentral.biz/api/salesOrders/actions/import
-> Request Headers
- Cache-Control : no-cache
- Postman-Token :
- Content-Length : 0
- Host :
- User-Agent : PostmanRuntime/7.32.1
- Accept : /
- Accept-Encoding : gzip, deflate, br
- Connection : keep-alive
- Authorization : Bearer TOKEN
- Content-Type : application/vnd.xentral.default.v1-beta+json
- POST create products https://ORGANISATION-ID.xentral.biz/api/products
-> Request Headers
- Cache-Control : no-cache
- Postman-Token :
- Content-Type : application/json
- Content-Length :
- Host :
- User-Agent : PostmanRuntime/7.32.1
- Accept : /
- Accept-Encoding : gzip, deflate, br
- Connection : keep-alive
- authorization : Bearer TOKEN
- content-type : application/vnd.xentral.default.v1+json
Body raw (json)
{
"project": {"id": "1"},
"measurements": {
"width": {"unit": "cm", "value": float},
"height": {"unit": "cm", "value": float},
"length": {"unit": "cm", "value": float},
"weight": {"unit": "kg", "value": float},
"netWeight": {"unit": "kg", "value": float}
},
"name": "string",
"number": "string",
"ean": "string",
"shopPriceDisplay": "float",
"description": "string",
"manufacturer": {
"name": "string",
"number": "string",
"link": "string"
},
"isStockItem": boolean,
"minimumOrderQuantity": integer
}
- POST create sales order https://ORGANISATION-ID.xentral.biz/api/salesOrders/actions/import
-> Request Headers
- authorization : Bearer TOKEN
- content-type : application/vnd.xentral.default.v1-beta+json Body raw (json)
{
"customer": {
"id": "integer"
},
"project": {
"id": "integer"
},
"financials": {
"paymentMethod": {
"id": "integer"
},
"billingAddress": {
"street": "string",
"country": "string",
"name": "string",
"city": "string",
"zipCode": "string",
"type": "string"
},
"currency": "string"
},
"delivery": {
"shippingAddress": {
"street": "string",
"type": "string",
"name": "string",
"zipCode": "string",
"city": "string",
"country": "string"
},
"shippingMethod": {
"id": "integer"
}
},
"date": "12/11/2023",
"positions": [
{
"product": {
"id": "integer"
},
"price": {
"amount": "float",
"currency": "string"
},
"quantity": integer
}
]
}
- GET list customers https://ORGANISATION-ID.xentral.biz/api/customers?filter[0][key]=email&filter[0][value]=%s.com&filter[0][op]=equals
-> Request Headers
- authorization : Bearer TOKEN
- accept : application/vnd.xentral.default.v1+json
-> Query Params
- filter[0][key] : email
- filter[0][value] : EMAIL VALUE
- filter[0][op] : equals
- GET list products https://ORGANISATION-ID.xentral.biz/api/products?filter[0][key]=number&filter[0][value]=%s&filter[0][op]=equals
-> Request Headers
- authorization : Bearer TOKEN
- accept : application/vnd.xentral.default.v1+json
-> Query Params
- filter[0][key] : number
- filter[0][value] : NUMBER VALUE
- filter[0][op] : equals