I would like to present a utility extension that has been developed in order to make Manager’s API v2 more usable. This tool will allow us to develop (hopefully with the support of @lubos in implementing the many missing features of API2) a series of extensions (advanced queries, BI, automations etc etc) that I will share here.
As is known, the REST API essentially mirrors the user interface: for every screen there is a “list” endpoint that returns what the UI shows and a set of “form” endpoints (GET / POST / PUT / DELETE) that operate on a single resource identified by its key.
This design is very flexible, but when one starts to build generic tools on top of it, a problem immediately arises: it becomes necessary to maintain an internal, up-to-date map of all endpoints, grouped by business function, and to distinguish clearly which endpoints are “lists”, which are “item GET”, which are “item PUT/POST/DELETE”, which relate to footers, custom fields, starting balances, and so on.
Hard-coding this knowledge inside each extension is fragile and makes maintenance extremely expensive whenever the API surface evolves. The goal of the extension described here is therefore to create a separate, re-usable “API mapping layer” which can be exported, versioned and consumed by any other Manager extension or external tool.
1. What the extension does
The extension (visible in the screenshots as “Manager API Mapper (TSV + JSON)”) performs four main functions:
- Loads and analyses the OpenAPI v2 specification exposed by Manager.
The OpenAPI URL and token header / token value can be configured in the “Connection & settings” panel. For security reasons the token is stored only in the browser (localStorage). The user may choose whether or not the token should be included in the exported mapping files. - Lets the user classify endpoints into business “Modules”, technical “Rules” and hierarchical “Folders”.
- Modules represent functional domains such as “Sales Invoices”, “Purchase Invoices”, “Bank Transactions”, “Custom Fields” and so on.
- Rules describe the technical role of the endpoint, for example
LIST-GET,ITEM-GET,ITEM-POST,ITEM-PUT,LIST-GET-FOOTER, etc. - Folders are a purely organisational layer that can contain sub-folders and to which modules can be assigned via drag & drop (see the screenshots). This allows the creation of trees such as “Bank Transactions → Receipts and Payments” or “Invoices → Sales Invoices, Debit Notes, Purchase Invoices”.
- Provides a full, filterable endpoints table.
After the OpenAPI spec is loaded, every endpoint is listed with:
- an internal row number,
- a “Use” flag (to mark endpoints that will be actually used in downstream projects),
- HTTP method,
- path,
- assigned module and rule,
- description (from the OpenAPI spec),
- free-text “Tags” and “Notes”.Sorting by any column is supported. Column headers remain fixed when the table scrolls. Endpoints can be previewed by clicking on the HTTP method (GET, POST, PUT, DELETE); if the endpoint requires a key or parameters, the extension will ask for them and then perform a live call to show the resulting JSON, which can be downloaded from the preview dialog. All parameters defined in the OpenAPI spec are parsed and stored in the mapping (including booleans, enums, arrays and other structured types), although they are not all shown in the main grid in order to keep it compact.
- Exports and imports the mapping as TSV or JSON, with fine-grained selection.
At the bottom of the interface there is a unified “Export / import (TSV & JSON)” section. The user can:
- choose the format (TSV, optimised for editing in Excel, or JSON, optimised for programmatic consumption);
- choose which rows are included using three boolean switches that act with AND logic:
- “Selected folders” (only endpoints belonging to folders currently marked for export),
- “Use flag (Use = 1)” (only endpoints flagged as “used”),
- “Active filter (Filter builder)” (only endpoints currently matched by the filter described below);
- generate the textual representation with “Build representation”;
- review or manually edit the content in the text area;
- import a TSV/JSON file, which is parsed and reflected back into the UI (modules, rules, folders, tags, notes, filter presets, OpenAPI URL, and, optionally, the token);
- save the mapping to a file with the correct extension.
In this way the mapping can be version-controlled, shared across businesses, and used as a configuration input for other extensions.
2. Advanced filtering with the “Filter builder”
When the number of endpoints grows, it becomes essential to have powerful querying tools. The extension therefore embeds a “Filter builder”, accessible from the “Endpoints” section.
The Filter builder allows the user to construct complex conditions using groups combined with AND / OR logic. Filters can reference HTTP method, path, module, rule, folder, description, notes, tags and the Use flag. The resulting filter is applied to the endpoints grid and can be indicated as active in the export section.
Moreover, filter configurations themselves can be saved, loaded, renamed and deleted. These presets are stored together with the mapping in the TSV/JSON file. This feature is particularly useful to maintain, for example, a saved view that selects all “LIST-GET” endpoints of invoice modules, or all endpoints related to custom fields, without having to rebuild the filter manually each time.
3. Parameters, preview and logging
The extension also focuses on understanding how each endpoint must be called:
- All parameters defined in the OpenAPI spec (including query parameters such as
term,sortBy,fields,pageSize, etc.) are parsed and recorded. Their type information and enum lists are preserved in the mapping, so that downstream tools know exactly which switches and drop-downs must be presented to the user when calling the endpoint. - When the user clicks on the HTTP verb in the grid, the extension opens a dialog where it becomes possible to:
- specify the key (if required);
- set all parameters required or optional, using appropriate controls depending on their type;
- execute the request and see a live JSON preview of the response;
- download that JSON to a file.
- At the bottom of the main window there is a collapsible log panel. Every relevant action is logged: spec loading and re-loading (with endpoint count and version), import / export operations, application of representations, filter changes, module / rule / folder operations, and preview calls. The log can be cleared, copied or saved as a text file.
This logging is important both for debugging during development and for maintaining an auditable trail of changes when the mapping is used in a production environment.
4. Workflow and intended usage
The intended workflow is as follows:
- Initial mapping.
The extension is opened in a given business, the OpenAPI URL and token header/value are set, and the spec is loaded. The user then:
- defines a set of business modules,
- defines a set of technical rules,
- organises modules inside folders,
- assigns each endpoint a module and rule,
- optionally adds tags and notes.
- Refinement with filters and presets.
Using the Filter builder, the user creates and saves useful presets (for example “core accounting endpoints”, “inventory-related endpoints”, “all list endpoints”, and so on). - Export.
When satisfied, the user builds a representation in TSV (for inspection or manual refinement in Excel) or JSON (for direct use in code) and saves it. The file also captures the OpenAPI URL, the mapping of modules, rules and folders, the saved filters and, optionally, the token. - Consumption by other extensions.
Other Manager extensions or external services can now load this TSV/JSON mapping and use it as a configuration file. A typical pattern is:
- identify, for a given module, which endpoint is the “LIST-GET” and which is the “ITEM-GET”;
- call the “LIST-GET” endpoint to obtain all keys;
- iterate over the keys with the “ITEM-GET” endpoint to build a denormalised table of all fields of that entity type;
- exploit the UUIDs and foreign keys returned to construct an in-memory relational model or to populate an external SQL database for reporting and business-intelligence purposes.
Because the mapping is independent from any particular extension, future modules (e.g. for custom field analysis, reporting, batch operations, synchronisation with external systems, or an SDK-like layer) can all rely on the same central description of the API.
5. Conclusion
This extension is therefore not an end-user feature in the traditional sense, but a meta-tool designed to make Manager’s API v2 easier to understand, document and exploit in a systematic way. It creates a bridge between the very flexible but UI-oriented REST design of Manager and the needs of developers and power users who want to build reusable, maintainable solutions on top of it.
The attached screenshots illustrate:
-
the configuration of modules, rules and folders,
-
the endpoints grid with sorting, tags and notes,
-
the export / import section with TSV/JSON representation,
-
and the Filter builder with its presets.
