Skip to content
Developerhome
Product homepage
Sage 200

API Methods

  Less than to read

Sage 200 web screen behaviour is controlled by various components that interact with each other. Understanding these components is essential for building and managing forms effectively. In this guide, we’ll explore the key components involved and their functionalities.

Redux State

The Redux state component serves as the master copy of the screen’s data. It typically loads data from an API using a GET call. This data is then used to populate the screens and construct API requests for updates (PUT/POST). By maintaining a central state, Redux ensures consistency and facilitates easy data management across the application.

Metadata

Metadata is crucial information about the screen’s data structure which is obtained from the API endpoint. You can retrieve metadata by using the $metadata query parameter in the API request. Metadata returned by the API will automatically include spare fields and any add-in fields that were added using the SageObjectStoreBuilder tool.

The web screens use metadata to understand the shape of the data when constructing API requests. Without loading metadata, the screen updates will fail because the framework won’t know which fields to include in the request body. Thus, loading metadata is vital for proper screen functioning.

InitialValues

The InitialValues component acts as a secondary copy of the screens data. It serves two primary purposes:

a. Determining Screen Dirtiness: Screen dirtiness refers to detecting if any changes have been made to the screens data. This information is used to enable the save button and display a prompt to the user when attempting to navigate away without saving changes.

b. Validation and Error Display: The InitialValues component provides values for screen validation and displaying errors or warnings on the screen. It initialises the data using an internal prop called initialValues on each screen.

It’s important to note that each screen has its own version of InitialValues. Child dialogs also maintain their independent version, meaning there can be different processing and configuration when extending the main screen versus using a child dialog.

API Methods

API methods enable developers to interact with the backend API and perform basic CRUD operations. These methods facilitate data retrieval, updating, and creation. They interact with the Redux store and Utilise metadata to define the shape of the data.

  • apiGetMetadata: This method retrieves the metadata from the API. It should be called before performing any updates to the endpoint. By fetching metadata, the front-end understands the data structure required for building API requests accurately.

  • apiGet: The apiGet method is used to retrieve data from the API. It unpacks the data from a single object into an array of separate key/value pairs, making it easier to bind to different field controls (e.g., textboxes, decimal inputs).

  • apiPut: This method is used to update data for an existing item. It should be called only after retrieving the metadata using apiGetMetadata and fetching the relevant data using apiGet. The apiPut method expects an ID parameter to identify the item being updated.

  • apiPost: The apiPost method is used to create a new item. Like apiPut, it should be preceded by a call to apiGetMetadata. You can preset any necessary values on a brand new item using the appropriate “set state” methods.

  • apiDelete: The apiDelete method allows you to delete a specific item from the backend, exercise caution when using this method.

  • apiGetCollection & apiPutCollection: These methods work with data arrays or collections. They are used when reading and updating multiple items, typically when the data is displayed in a grid on the screen. Before using these methods, it’s essential to call apiGetMetadata to define the structure of the API request.

Child Methods

Child methods are similar to API methods but operate on child objects or collections of hierarchical data already present on the screen. These methods interact with the Redux store, leveraging metadata to define the data structure and refreshing the screen’s initialValues for validation and dirtiness.

  • childGet: The childGet method is used to retrieve data from the parent object, which is typically a collection. This collection can be either on the core web screen or obtained using apiGetCollection. It should be called after invoking childGetMetadata.

  • childPut: This method updates the parent object, usually a collection, with the child’s modified data. It should be called after childGetMetadata and childGet to ensure proper data flow.

  • childGetMetadata: This method retrieves metadata at the child level from the parent’s metadata. It assumes that the parent’s metadata is already accessible within the Redux store on the parent screen. The childGetMetadata call is necessary to define the shape of the data that will be sent back to the parent.

  • childGetCollection & childPutCollection: These methods are used when working with collections of child objects. They allow copying and updating data in a grid or similar UI element. These methods are employed when the screen needs to maintain a temporary copy of the data for scratchpad use. The data can be discarded if the user cancels the screen or saved if the user selects the save option.