Versions Compared

Old Version 36

changes.mady.by.user Kristofers Sevcenko

Saved on

compared with

New Version 37

changes.mady.by.user Kristofers Sevcenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

...

Section


Column
width30%

Retrieving the database structure of a register

To generate the various end-points Burti API relies on the database structure that Standard ERP exposes via the Export/import Format report in its' Technics module.

When the report is run without specifying a register code, it will dump the database definitions of all the registers in the database. These are for example Invoices, Sales Orders, Deliveries and such.

You will need to look up the register(-s) that you wish to expose via the API in this report and then separately export these to a text file.

Example

In this example we show how to retrieve the database structure of the Orders register to use for creating its' API end-point.

Step 1: Enter the keyword "Orders" in the search field of the report

Step 2: Cycling through the search results pin-point the correct register and take note of its' code (ORVc).

Step 3: Reopen to the Report Specification window using the cogwheel menu available in the upper-left hand corner of the window.

Step 4: Enter the register code (ORVc in this example) in the field labeled "Vc (View Code)", set Media to File and press Run to save the definition in a file.


Column
width70%


...

FileRole
halcust/serverJSON/generated-interfaces/JSON_InterfaceCallers.hal 

This is is the main entry point for all API calls. Think of it as a router. Everything will go through this file and get re-routed to the appropriate API sub-routines.

Info

You won't need to ever make changes to this file.


Note

This file will always be re-generated when changing the API configuration.



Info

The register code for Orders - ORVc - is used, but this part of the filename will change according to whatever register you are setting up the API for.


halcust/serverJSON/generated-interfaces/JSON_ORVc.hal 

This is the main Read API functionality. It contains code for all the indexing, filtering and include/exclude options you selected.

Info

You won't need to ever make changes to this file.


Note

This file will always be re-generated when changing the API configuration.


halcust/serverJSON/generated-interfaces/JSON_ORVc_Tools.hal (lightbulb)

This file is where the Read API customisation happens. This contains all the available HAL hooks that you can take advantage of to either include additional data or add custom filtering or other behavior to the API.

The various possibilities are documented towards the end of the documentation.

halcust/serverJSON/generated-interfaces/JSON_Save_ORVc.hal 

This is the main Write API functionality. It's responsible for populating the record with the field values that you pass via the API.

Info

You won't need to ever make changes to this file.


Note

This file will always be re-generated when changing the API configuration.


halcust/serverJSON/generated-interfaces/JSON_Save_ORVc_Tools.hal (lightbulb)

This file is where the Write API customisation happens. This contains all the available HAL hooks that you can take advantage of to either include record validations, additional calculations, changes to other linked records etc.

The various possibilities are documented towards the end of the documentation.


Read API

Entry point

The All Read API is accessed via the following single entry-point URL:

Code Block
languagetext
 https://your.server.address/Web_JSON_Composer.hal 

Batch requests

The API allows for multiple requests to be made simultaneously in one call. Depending on the application this can have advantages, mostly performance related. This is done by prefixing all API call parameters with a request number, starting with zero.

Info

This means that parameter1 and parameter2  become 0_parameter1 and 0_parameter2 and if you do chain multiple requests together, then all subsequent request parameters are prefixed by an incremented number.

Look for examples below the parameter descriptions on how to piece this together.

Parameters

ParameterUsage

query 

This routes the API to the specific register's end-point. This is supplied in the following format:

Code Block
Web_JSON_<register-code>_List.hal

So for example for the Orders register with code ORVc the end-point becomes Web_JSON_ORVc_List.hal 

company The company number from which you wish to the data to be retrieved.

full 

(optional)

Set this to true  to retrieve the full data set (as defined using the "In full" column in the API Register Definition record as described earlier).

Defaults to false 

count 

(optional)

The number of records to return.

Defaults to 50 

offset 

(optional)

Used together with the count  paramete to skip the first set of records when employing a paginated record retrieval approach (i.e. offset of 50 with count of 50 would mimic requesting a second page of 50 records).
since_seq 

(optional)

All data sets for registers that support sequencing/sequence numbers are returned along with the current database sequence number - a counter that is increased when a change is made in the respective register. If you record this number and then use it as the since_seq  parameter in subsequent calls, you can retrieve only the records that have changed since the previous data request.
index 

(optional)

Select the index you wish your data to be sorted by or looked up by. Must be defined in the API Register Definition.

Defaults to the main key specified on the API Register Definition.

sort_only 

(optional)

If you do not wish to lookup data by specific values of the fields in the specified index, you can set this to true to only apply a sort by this index.

Defaults to false 

sort_order 

(optional)

Set to back to apply a descending sort order.

Defaults to forward 

fieldcnt 

(optional)

When looking up data by specific index field values, you must specify the index segment/field count to use.

Defaults to none 

fieldlist 

(optional)

When looking up data by specific index field values, you must specify the field names by which to perform the lookup.

This is then accompanied with additional dynamic fieldname-named parameters.

Example: index=CustCode&fieldcnt=1&fieldlist=CustCode&CustCode=05131 

Note

This is a pseudo-example, as you always have to prepend the parameter names with the request's index. In single-request calls use 0  (0_index and so on).


Info

When using indexes with date fields for lookups you can either lookup by a single specific date or use a date range. To use a lookup by range, add another parameter along with the date field, with the string "-until" appended.

Example: When using field OrderDate you can use either just the OrderDate=2020-01-01  for a single date or both OrderDate=2020-01-01  and OrderDate-until=2020-01-31 for a full month.

You do not need to list the -until  parameter in fieldlist 

Date format is YYYY-MM-DD  everywhere on the API.


new 

(optional)

This parameter will return a blank record to be used as a template for populating a new record.

debug 

(optional)

Set this to on to enable debug logging in hansa.log  for each API call. This will give performance statistics of the call.

Default value is off 

paramlist 

(optional)

Use this to list parameter names that you wish to see the values of dumped to the debug information log.


Write API


Section


Column
width30%



Column
width70%



...