i2Rest Client API

From i2Rest
Revision as of 22:30, 3 September 2020 by Alexei.baranov (talk | contribs) (→‎C definition and usage)
Jump to: navigation, search

i2Rest Client API functions

i2Rest Client API is a set of functions exported by the service program named I2REST. You can embed calls to these functions into your ILE RPG or ILE C code to enhance it with interactions with several public or private web servers. i2Rest Client and i2Camunda are built using this API functions.

The service program is located in i2Rest distribution library (default library name is I2REST)

i2Rest Client API service program is compiled using *TERASPACE storage model, and requires the same storage model to be used in programs that calls i2Rest Client API functions.

It is possible to use any preferred ILE compiler. Examples of structures and prototypes of functions for ILE C and ILE RPG languages are given below in the document.

The list of i2Rest Client API functions is follows:

  • i2rest_POST_data
  • i2rest_request_authorize
  • i2rest_request_bridge_authorize
  • i2rest_wait_authorization
  • i2rest_get_fresh_token
  • i2rest_get_access_token
  • i2rest_request_client_credentials_token
  • i2rest_qr_available
  • i2rest_draw_qr
  • i2rest_create_handler_ex
  • i2rest_free_connection_handler

Common structures

i2rest_string

This structure is used as input / output parameter for variable length strings. You can create static instances of such structures, or allocate it dynamically using %Alloc (malloc in ILE C) function. When using %Alloc, do not forget to %Dealloc it after use.

C definition and usage

typedef struct i2rest_string i2rest_string;
struct i2rest_string
{
   unsigned int provided;              // Size of space provided for input/output data in bytes
   unsigned int available;             // Size of data available in response. It could be greater than provided,
   char         data[];                // but in any case data will contain not more than "provided" bytes
};

// Dynamic allocation
i2rest_string *s;
s=malloc(sizeof(i2rest_string)+5000);
memset(s, ' ', sizeof(i2rest_string)+5000);
s->provided=5000;
s->available=0;
...
free(s);

// Static allocation
char           bs[sizeof(i2rest_string)+5000];
i2rest_string *s=(void *)bs;
memset(s, ' ', sizeof(i2rest_string)+5000);
s->provided=5000;
s->available=0;
...

RPGLE definition and usage

D i2r_str5000     DS                  Qualified
D   provided                    10I 0 
D   available                   10I 0        
D   data                      5000A                

 * Static allocation
D s5000           DS                  LikeDS(i2r_str5000)
...
 /Free
    s5000.provided=5000;
    s5000.available=0;
    s.data=' ';
 /End-free

i2rest_payload

This structure is used as input parameter to define request payload - request body and/or attachments.

C definition and usage

typedef struct i2rest_payload i2rest_payload;
struct i2rest_payload
{
   char name[512];         // Name of IFS file that contains request payload. 
   char body[5000];        // Request payload in form of simple string
   char id[512];           // When using this payload as attachment, this field defines ID for this attachment  
   char mime_type[100];    // attachment's mime type
   char convert[4];        // "*YES" - convert attachment before sending, "*NO " - do not convert
   unsigned int toccsid;   // use this CCSID as destination CCSID when converting file/string before sending
};

i2rest_payload body;
memset(&body, ' ', sizeof(i2rest_payload));
// simple string
strcpy(body.body, "{\"hello\":\"world\"}";
strcpy(body.mime_type, "application/json");
// or file payload
strcpy(body.name, "/usr/myfile.json";
strcpy(body.mime_type, "application/json");
strcpy(body.convert, "*YES");
body.toccsid=1208; // utf-8. /usr/myfile.json can have another encoding, i2Rest will convert it automatically

RPGLE definition and usage

D i2r_payload     DS                  Qualified
D   name                       512A  
D   body                      5000A  
D   id                         512A  
D   mime_type                  100A  
D   convert                      4A  
D   to_ccsid                    10I 0

D body            DS                  LikeDS(i2r_payload)
...
 /Free
    body.mime_type='application/json';
    body.body='{"hello":"world"}';    
 /End-free

i2rest_header

This structure is used as input parameter to define extra headers for request.

C definition and usage

typedef struct i2rest_header i2rest_header;
struct i2rest_header
{
   char name[512];       // header name
   char value[5000];     // header value
};

i2rest_header headers[2];
memset(&headers, ' ', sizeof(headers));
strcpy(headers[0].name,  "HEADER1";
strcpy(headers[0].value, "HEADER1 value";
strcpy(headers[1].name,  "HEADER2";
strcpy(headers[1].value, "HEADER2 value";

RPGLE definition and usage

D i2r_header      DS                  Qualified
D   name                       512A  
D   value                     5000A  

D headers         DS                  LikeDS(i2r_header) Dim(2)
...
 /Free
    headers(1).name='HEADER1';
    headers(1).value='HEADER1 value';
    headers(2).name='HEADER2';
    headers(2).value='HEADER2 value';
 /End-free

Qus_EC_t

This structure is used as input/output parameter for error code parameter.

C definition and usage

This parameter conforms to common error code parameter that is used in IBM i API. typedef definition is included in <qusec.h> header file.
Sample usage: 

char       error_code_internal[5000];
Qus_EC_t  *error_code;
...
error_code=(void *)error_code_internal;
memset(error_code, 0, sizeof(error_code_internal));
error_code->Bytes_Provided=sizeof(error_code_internal);
...

RPGLE definition and usage

D Qus_EC_t        DS           256    Qualified
D   Bytes_Avail                 10I 0          
D   Bytes_Prov                  10I 0          
D   ExceptionID                  7A            
D   reserved                     1A            
D   ExceptionDT                240A             
 *
D error_code      DS                  LikeDS(Qus_EC_t)
...
 /Free
    error_code.Bytes_Avail=0;
    error_code.Bytes_Prov=256;
 /End-free

i2rest_POST_data

This function is used for make requests to API servers.

C prototype

int i2rest_POST_data(void              **p_handler,             // pointer to request handler, input/output
                     char               *api_url,               // input - api endpoint (zero-terminated string)
                     char               *method,                // input - HTTP request method
                     i2rest_string      *api_resp,              // input/output - pointer to i2rest_string to save API response 
                     char               *file_resp,             // input - file name to save API response
                     char               *replace,               // input - "*YES"=replace output file
                     int                 file_ccsid,            // input - file CCSID that will be used for newly created API response file
                     int                 convert,               // input - 1=convert response to destination file CCSID,
                                                                //         0=save response without conversion
                     i2rest_payload     *body,                  // input - request body, pointer to i2rest_payload structure
                     i2rest_header      *headers,               // input - extra headers, pointer to array of i2rest_header structures
                     int                 headers_cnt,           // input - number of records in headers array
                     i2rest_payload     *attachments,           // input - request attachments, pointer to i2rest_payload array
                     int                 att_cnt,               // input - number of records in attachments array
                     i2rest_string      *token,                 // input - pointer to i2rest_string that contains access token
                     i2rest_string      *client_id,             // input - pointer to i2rest_string that contains value of client_id parameter
                     i2rest_string      *client_pw,             // input - pointer to i2rest_string that contains value of client_secret
                     char               *dcm_cl_id,             // input - DCM client ID (zero-terminated string)
                     char               *recv_log,              // input - file to log received messages (zero-terminated string)
                     char               *sent_log,              // input - file to log sent messages (zero-terminated string)
                     Qus_EC_t           *error_code);           // input/output - error code parameter

RPGLE prototype

D i2rest_POST_data...                                                                                              
D                 PR            10I 0 ExtProc('i2rest_POST_data')          Return code                             
D    p_handler                    *                                                                                
D    api_url                      *   Value Options(*String)               API endpoint                            
D    method                       *   Value Options(*String)               HTTP Method                             
D    api_resp                     *   Value                                API response                            
D    file_resp                    *   Value Options(*String)               File to save response                   
D    replace                      *   Value Options(*String)               Replace response file?                  
D    file_ccsid                 10I 0 Value                                Response file CCSID                     
D    convert                    10I 0 Value                                Convert response?                       
D    body                         *   Value                                Body string/file                        
D    headers                      *   Value                                Extra headers                           
D    headers_cnt                10I 0 Value                                Number of extra headers                 
D    attachments                  *   Value                                Attachments                             
D    att_cnt                    10I 0 Value                                Number of attachments                   
D    token                        *   Value                                OAuth2 token                            
D    client_id                    *   Value                                OAuth2 client id                        
D    client_pw                    *   Value                                OAuth2 client secret                    
D    dcm_cl_id                    *   Value Options(*String)               DCM Client application ID (z-terminated)
D    recv_log                     *   Value Options(*String)               recv log file (z-terminated)            
D    sent_log                     *   Value Options(*String)               sent log file (z-terminated)            
D    error_code                   *   Value

Parameters description

Parameter Type Description Default value
p_handler pointer to pointer Pointer to i2Rest Client API handler

If passed as pointer to NULL value, i2Rest will create new i2Rest Client API handler and return here its value. You can pass this pointer to all subsequent calls to i2Rest Client API functions to avoid unnecessary initialization steps. Use i2rest_free_connection_handler to release allocated resources.
If not passed, i2Rest Client API will create temporary API handler and release allocated resources after call.

Null (temporary API handler will be created)
api_url pointer to zero-terminated string REQUIRED. API endpoint

i2rest_POST_data will send request to this URL. It can start from http://, https:// or file:// prefix

method pointer to zero-terminated string REQUIRED. HTTP method

One of:

  • *POST
  • *GET
  • *PUT
  • *DEL
api_resp pointer to i2rest_string structure i2rest_string structure to save response string

If passed, and "provided" is greater than zero, i2rest_POST_data will save not more than "provided" bytes of response into "data" part of i2rest_string.
If passed, i2rest_POST_data will save overall response size to "available" part of i2rest_string. If "provided" is not enough to save all response to "data", only "provided" bytes will be saved, and "available" will be greater than "provided".

Null. i2rest_POST_data will not return response data in api_resp parameter
file_resp pointer to zero terminated string Name of file to save response

If passed, i2rest_POST_data will save response body to specified file.
If file is exist and "replace" is not equals to "*YES", exception will be thrown (see error_code parameter).
If file is not exist, it will be created with "file_ccsid" code page.
If "convert" parameter is equals to 1 than response body will be automatically converted to "file_ccsid" before saving. 0 - response will be saved without conversion.

Null. i2rest_POST_data will not save response data to file_resp file
replace pointer to zero terminated string Replace file?

Value "*YES", "*NO" or NULL (*Null in RPGLE). Null has the same meaning as *NO. See file_resp parameter.

Null
file_ccsid int File CCSID to save response

See file_resp parameter.

convert int Convert response to file CCSID?

See file_resp parameter.

body pointer to i2rest_payload structure Request body

Required for *POST and *PUT methods
If passed, i2rest_POST_data will use "body" string or content of file named "name" as a request body. "name" parameter has priority - i2rest_POST_data will use file content instead of body string.
If "mime_type" part of body is empty, "application/json" will be used with string body content and "text/plain" - with file body content.
"id" part of body is ignored
When using file content, "convert" and "to_ccsid" parts can be set to convert file data before sending to API endpoint.

headers pointer to array of i2rest_header structures Extra headers

If passed, i2rest_POST_data will set extra request headers using this array

headers_cnt int Number of extra headers

Defines the number of records in headers array

attachments pointer to array of i2rest_payload structures MIME attachments

It is possible to define the list of files or strings that will be sent to API endpoint as MIME attachments. The meaning i2rest_payload structures is the same as described in body parameter
The "id" part of i2rest_payload structure can be used to define id of MIME attachment. The special value "*SAME" can be used to send file name as ID of MIME attachment

att_cnt int Number of MIME attachments

Number of records in attachments array

token pointer to i2rest_string structure i2rest_string structure with the value of OAuth2 access token

If passed, and "provided" is greater than zero, i2rest_POST_data will use "provided" bytes of "data" part as a value of OAuth2 access token. The token will be sent in Authorization:Bearer header

 Null. i2rest_POST_data will not send OAuth2 token to API endpoint
client_id pointer to i2rest_string structure i2rest_string structure with the value of Client/User ID

If passed, and "provided" is greater than zero, i2rest_POST_data will use "provided" bytes of "data" part as a value of User ID part of Authorization:Basic header

 Null. i2rest_POST_data will not send Authorization:Basic header
client_pw pointer to i2rest_string structure i2rest_string structure with the value of Client/User password

If passed, and "provided" is greater than zero, i2rest_POST_data will use "provided" bytes of "data" part as a value of Password part of Authorization:Basic header

 Null. i2rest_POST_data will not send Authorization:Basic header
dcm_cl_id pointer to zero terminated string DCM client ID

It is required to pass dcm_cl_id parameter when dealing with https:// endpoints. Please have a look at Create_Client_Application for step by step guide how to create DCM Client application ID

Null
recv_log pointer to zero terminated string Name of IFS file to log received messages

Use this parameter for logging responses

Null
sent_log pointer to zero terminated string Name of IFS file to log sent messages

Use this parameter for logging requests

Null
error_code pointer to Qus_EC_t structure error_code parameter

If NOT passed (NULL/*Null), i2rest_POST_data will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint.
If passed, i2rest_POST_data will set standard Qus_EC_t structure with details of unrecoverable errors.

Null

Return parameter

i2rest_POST_data returns integer value of HTTP response status (values greater than 200), or one of following negative values together with error_code parameter:

  • -1, I2R0023 File &1 is already exist. File to save response already exist and *NO specified in "replace" parameter
  • -1, I2R0018 Unable to open stream file &1 for writing. It is impossible to create new file for save API response
  • -1, I2R0015 Unable to open stream file &1 for reading
  • -1, I2R0017 Content type is not specified &1
  • -3, I2R0016 Unable to post API message. &1
  • -3, I2R0018 Unable to open stream file &1 for writing. It is impossible to save API response to file
Retrieved from "https://www.i2rest.com/index.php?title=I2Rest_Client_API&oldid=1809"