API Entities, Fields, and Actions

The contract of an endpoint defines the following elements of the contract-based REST API: entities, fields, and actions.

Entities

An entity corresponds to a business logic object that you are going to work with. For example, the contract of a system endpoint includes the Warehouse entity, which represents a warehouse and holds the data related to the warehouse. This entity is associated with the Warehouses (IN204000) form.

For a custom endpoint, if you are going to use an entity to transfer data to or from MYOB Acumatica, you should associate this entity with a particular MYOB Acumatica form. For example, you can create a TrialBalance entity, which represents a trial balance. This entity is associated with the Trial Balance (GL303010) form.

Fields

The fields of an entity correspond to the parameters of a business logic object. For example, the Warehouse entity that is available through a system endpoint has the Description and WarehouseID fields, among others. In the contract, these fields are mapped to the Description and the Warehouse ID elements of the Summary area of the Warehouses (IN204000) form.

For a custom endpoint, if you need to connect the field with a particular element on an MYOB Acumatica form, you should map the field to this element. For example, if you have created the TrialBalance entity, which designates a trial balance, you can add the ImportNbr field to the entity and connect this field with the Import Number element of the Summary area of the Trial Balance form.

Actions

The actions of an entity correspond to the actions that can be applied to a business logic object. For example, the TransferOrder entity, which is available through a system endpoint, has the ReleaseTransferOrder action. This action corresponds to the Release button on the form toolbar of the Transfers (IN304000) form.

For a custom endpoint, if you need to use an MYOB Acumatica action, you should add this action to the contract of the custom endpoint with the needed parameters. For example, suppose you want to add an action that changes the customer ID of an existing customer, you can add the action ChangeID and map it to the Change ID action, which is available on the Customers (AR303000) form. The new action should have one parameter, which specifies the new ID of a customer as the Change ID action has.

Types of Entities

When you add a new entity to a contract, you should specify the type of the entity, which can be one of the following:
  • Top-Level: Entities of this type are the main entities of the contract. A top-level entity usually corresponds to an MYOB Acumatica form. For example, the Warehouse entity of the contract of a system endpoint is a top-level entity that corresponds to the Warehouses (IN204000) form.
  • Detail: Detail entities correspond to the detail lines of a master-detail form. A detail entity exists only as a part of a top-level entity. For example, the top-level entity SalesOrder of the contract of a system endpoint contains the detail entity SalesOrderDetail, which corresponds to a detail line on the Details tab of the Sales Orders (SO301000) form, as shown in the following screenshot.
    Figure 1. Detail entity


  • Linked: Linked entities are supplementary entities of a contract. A linked entity usually corresponds to a part of an MYOB Acumatica form and is related to one top-level entity of the contract or multiple such entities. For example, the top-level entity Contact of the contract of a system endpoint contains the linked entity Address, which corresponds to the Address group of fields on the Details tab of the Contacts (CR302000) form, as shown in the following screenshot.
    Figure 2. Linked entity


  • Report: An entity of this type corresponds to an MYOB Acumatica report. For example, in a custom endpoint, you can create the CashAccountSummary report entity, which corresponds to the Cash Account Summary (CA633000) report.