API object - Insert service definition and declaration

This article describes all the necessary steps to declare, inside an API object called APICustomers, an Insert service that inserts a new customer into the Database.

Consider a Knowledge Base containing:

1) A Customer Transaction object:

Customer
{
  CustomerId*
  CustomerName
  CustomerLastName
}  

Note: The Customer Transaction has Automatic data population.

2) An API object called APICustomers. In its Service Source tab, it already contains two services declared that map external names exposed as services with the internal implementations in the KB:

Now, suppose you need to define another service (method) named Insert, as part of the APICustomers object, to allow inserting a new Customer into the database (the customer data is sent as parameters). 

To achieve this, the Customer Transaction must be set as Business Component.

Next, you have to create a new Procedure object named CustomerInsert. 

In the Procedure Rules section, define a Parm rule as follows:

Parm(in:&CustomerId, in:&CustomerName, in:&CustomerLastName, out:&Messages);

In the Procedure Source, define the following code:

&Customer.CustomerId=&CustomerId 
&Customer.CustomerName=&CustomerName
&Customer.CustomerLastName=&CustomerLastName
If &Customer.Insert()
   commit
else 
   rollback
Endif 
&Messages= &Customer.GetMessages()

• &Customer is a variable based on the Customer Business Component data type.
• &Messages is a variable based on the Messages data type.

Now, go to the APICustomers API object, and inside its Service Source declare the new method (Insert) under the last method:

Customer{
    ...
    [RestMethod(POST)]
    Insert(in:&CustomerId, in:&CustomerName, in:&CustomerLastName, out:&Messages) => CustomerInsert(&CustomerId, &CustomerName, &CustomerLastName, &Messages);
}

Note that in this case, the RestMethod annotation precedes the service declaration indicating that the HTTP method to be used is POST.

The &CustomerId, &CustomerName, and &CustomerLastName variables are defined as input parameters (they are sent to be assigned). 

The &Messages variable is an output parameter that returns the messages obtained after performing the Business Component Insert method to inform the user if the operation was successful.

It is important to add the same variables you already defined in the Procedure object in the API object.

The next step is to define–if necessary–the Events in the Events section of the API object (APICustomers).

Event Insert.Before
    //Some Code if is needed
EndEvent
Event Insert.After
    //Some Code if is needed
EndEvent

The 'Insert.Before' and 'Insert.After' events will be executed on each invocation of the Insert method.

The order of events executed in this example is as follows:

1. Event 'Before'
2. Event 'Insert.Before'
3. Insert method (CustomerInsert procedure internally)
4. Event 'Insert.After'
5. Event 'After' 

Below you can see all the steps being executed: