Sections in this article
How API Calls Work
All API calls will be to a CL program that begins with AC_. This will call an RPG program with the prefix AR_. So AC_DELSUPL will call the RPG program AR_DELSUPL and return whether it was successful or not with a possible error message. You can refer to the File Field Descriptions to see what is the meaning of values being passed. These objects are contained in K3S_5OBJ.
API Unit Test
Each CL/RPG API will have a test program with the prefix TS_ to help test the API with no parameters needing to be supplied. The test program will call the CL which in turn calls the RPG. This ensures each individual piece works. EX: TS_ADDSUPL, when called, will add a test supplier that can be deleted by calling TS_DELSUPL.
Value Submit Meaning
For any program that is an Update to a record (for example UPDSUPL) any field with an ‘ID’ prefix will be non-updatable via the program and used for identification of what records should be updated in the database.
A prefix of ‘SB’ will be applied to the front of all fields where a value is ‘expected’ to be submitted.
A prefix of ‘RV’ will be applied to the front of all fields that are used to return values.
All APIs will assume that the values submitted will be in the order they are listed in the API guide, correctly defined alphanumerics or numerics, and no longer than the listed size. The API will validate the data otherwise.
API Logs
All API calls are logged in our API log and kept for a set number of days. The time called, time finished, and if it was completed or if there was an error is recorded.
Errors and MSGW
All MSGWs (or errors created from the API) should be responded to automatically with MONMSG. The API error is then recorded in the API log, and the values submitted and the error will be emailed to support department to be researched.
Example
Below is an example piece of code in PHP using the ZF3 Framework and the IBM i PHP Toolkit. This is used to setup the SUPL group of APIs, and then be able to call DELSUPL. Within our current user interface we have all APIs called via AJAX and return the response in JSON.
<?php
namespace RPG\Controller;
use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\JsonModel;
use K3sbase\Table\USERTable;
use ToolkitApi\Toolkit;
/**
* Class SuplController
* @package RPG\Controller
*/
class SuplController extends AbstractActionController
{
/**
* @var USERTable
*/
protected $USERTable;
/**
* @var array
*/
protected $config;
/**
* @var Toolkit
*/
protected $toolkit;
/**
* suplController constructor.
* @param USERTable $USERTable
* @param array $config
* @param Toolkit $toolkit
*/
public function __construct(USERTable $USERTable, array $config, Toolkit $toolkit)
{
$this->USERTable = $USERTable;
$this->config = $config;
$this->toolkit = $toolkit;
}
public function delsuplAction()
{
// This is the API object location. It is usually stored in the k3s_settings array for the setup
// An example of what woudl be in here would be: K3S_5OBJ
$K3SOBJ = $this->config['k3s_settings']['k3sobj'];
// This would be located in the company file
$COMP = $this->config['k3s_settings']['comp'];
$COMPCOD = $this->config['k3s_settings']['compcod'];
// USERID is retrieved from the ZFCUSER module for login.
// This is then gone to the K3S_5WEB.USER file, and found the user entry
// From there we can get the REPUSER (which is from K_USERPRF)
// This is the user we submit when running an API. We would expect them
// to be in the K_USERPRF file.
$USERID = $this->zfcUserAuthentication()->getIdentity()->getId();
$USEROBJECT = $this->USERTable->getUser($USERID);
$USER = $USEROBJECT->REPUSER;
$IDBUYR = $this->getRequest()->getPost('IDBUYR');
$IDLOCN = $this->getRequest()->getPost('IDLOCN');
$IDSUPL = $this->getRequest()->getPost('IDSUPL');
$IDSUPLSUB = $this->getRequest()->getPost('IDSUPLSUB');
$param[] = $this->toolkit->AddParameterChar('BOTH', 10, 'K3S Object Library', 'K3SOBJ', $K3SOBJ);
$param[] = $this->toolkit->AddParameterChar('BOTH', 1, 'Company', 'COMP', $COMP);
$param[] = $this->toolkit->AddParameterChar('BOTH', 3, 'Company Code', 'COMPCOD', $COMPCOD);
$param[] = $this->toolkit->AddParameterChar('BOTH', 10, 'User calling the program', 'USER', $USER);
$param[] = $this->toolkit->AddParameterChar('BOTH', 1, 'Error indicator', 'ERRORS', $ERRORS);
$param[] = $this->toolkit->AddParameterChar('BOTH', 100, 'Error message', 'ERRMSG', $ERRMSG);
$param[] = $this->toolkit->AddParameterChar('BOTH', 20, 'Field in error', 'ERRFIELD', $ERRFIELD);
$param[] = $this->toolkit->AddParameterChar('BOTH', 5, 'buyr', 'IDBUYR', $IDBUYR);
$param[] = $this->toolkit->AddParameterChar('BOTH', 5, 'locn', 'IDLOCN', $IDLOCN);
$param[] = $this->toolkit->AddParameterChar('BOTH', 10, 'supl', 'IDSUPL', $IDSUPL);
$param[] = $this->toolkit->AddParameterChar('BOTH', 10, 'suplsub', 'IDSUPLSUB', $IDSUPLSUB);
$result = $this->toolkit->PgmCall("AC_DELSUPL", $K3SOBJ, $param, null, null);
return new JsonModel(array(
'label' => 'Delete',
'result' => $result,
'errors' => $result["io_param"]["ERRORS"],
'errmsg' => $result["io_param"]["ERRMSG"]
));
}
