Revision as of 15:34, 4 September 2020

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. Generic requests to web servers with or without Basic/OAuth2 authorization
i2rest_request_authorize. Obtain user and device codes (first step of OAuth2 Device code flow)
i2rest_request_bridge_authorize. Get Bridge code (first step of OAuth2 Access code flow in i2Rest Bridge mode)
i2rest_wait_authorization. Get OAuth2 token (last step of OAuth2 Device code flow)
i2rest_get_fresh_token. Present refresh token and exchange it to new access token (OAuth2 Refresh token flow)
i2rest_get_access_token. Get Access code (second step of OAuth2 Access code flow in i2Rest Bridge mode)
i2rest_request_client_credentials_token. Obtain OAuth2 Client credentials token
i2rest_create_handler_ex. Create i2Rest Client API handler with extended parameters
i2rest_free_connection_handler. Release resources allocated for i2Rest Client API handler
i2rest_qr_available. Check for availability of drawing QR code
i2rest_draw_qr. Draw QR code

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

There is the example of i2rest_string structure with 5000 bytes of data:

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 to_ccsid;   // 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.to_ccsid=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 generic 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                    *                                        Pointer to void pointer                                        
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 equal to "*NO", 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? Required when file_resp is specified Value "YES", "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	Required. Name of IFS file to log received messages Use this parameter for logging responses. Empty string means no logging	Null
sent_log	pointer to zero terminated string	Required. Name of IFS file to log sent messages Use this parameter for logging requests. Empty string means no logging	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. I2R0004 Unable to initialize secured connection
-1, I2R0015 Unable to open stream file &1 for reading
-3, I2R0016 Unable to post API message. &1
-1, I2R0017 Content type is not specified &1
-1, I2R0018 Unable to open stream file &1 for writing. It is impossible to create new file for save API response
-3, I2R0018 Unable to open stream file &1 for writing. It is impossible to save API response to file
-1, I2R0023 File &1 is already exist. File to save response already exist and *NO specified in "replace" parameter

i2rest_request_authorize

This function is used at the first step of OAuth2 Device code flow to obtain user code, device code and verification url(s).

C prototype

int  i2rest_request_authorize(void               **p_handler,     // pointer to request handler, input/output
                              i2rest_string       *ver_url,       // input/output - pointer to i2rest_string to save verification url
                              i2rest_string       *ver_url_l,     // input/output - pointer to i2rest_string 
                                                                  // to save complete verification url (with user code)
                              i2rest_string       *user_code,     // input/output - pointer to i2rest_string to save user code
                              i2rest_string       *device_code,   // input/output - pointer to i2rest_string to save device code
                              int                 *expires_in,    // output - pointer to int value. Expiration time for device and user codes
                              int                 *interval,      // output - pointer to int value. Interval for checking token availability
                              char                *auth_url,      // input - pointer to authentication endpoint (zero-terminated string)
                              char                *client_id,     // input - pointer to client_id value (zero-terminated string)
                              char                *client_pw,     // input - pointer to client_secret value (zero-terminated string)
                              char                *scope,         // input - pointer to scope value (zero-terminated string)
                              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_request_authorize...                                                                                              
D                 PR            10I 0 ExtProc('i2rest_request_authorize')  Return code                             
D    p_handler                    *                                        Pointer to void pointer                                        
D    ver_url                      *   Value                                verification_url (pointer to i2rest_string)                           
D    ver_url_l                    *   Value                                verification_url_complete (pointer to i2rest_string)
D    user_code                    *   Value                                user_code (pointer to i2rest_string)
D    device_code                  *   Value                                device_code (pointer to i2rest_string)
D    expires_in                   *   Value                                expires_in (pointer to int)
D    interval                     *   Value                                interval (pointer to int)
D    auth_url                     *   Value Options(*String)               Authentication endpoint (z-terminated)
D    client_id                    *   Value Options(*String)               client_id (z-terminated)
D    client_pw                    *   Value Options(*String)               client_secret (z-terminated)
D    scope                        *   Value Options(*String)               scope (z-terminated)
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)
ver_url	pointer to i2rest_string structure	i2rest_string structure to save returned verification_url If passed, and "provided" is greater than zero, i2rest_request_authorize will save not more than "provided" bytes of returned verification_url into "data" part of i2rest_string. If passed, i2rest_request_authorize will save overall length of returned verification_url 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_request_authorize will not save returned verification_url
ver_url_l	pointer to i2rest_string structure	i2rest_string structure to save returned verification_url_complete If passed, and "provided" is greater than zero, i2rest_request_authorize will save not more than "provided" bytes of returned verification_url_complete into "data" part of i2rest_string. If passed, i2rest_request_authorize will save overall length of returned verification_url_complete 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_request_authorize will not save returned verification_url_complete
user_code	pointer to i2rest_string structure	i2rest_string structure to save returned user_code If passed, and "provided" is greater than zero, i2rest_request_authorize will save not more than "provided" bytes of returned user_code into "data" part of i2rest_string. If passed, i2rest_request_authorize will save overall length of returned user_code 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_request_authorize will not save returned user_code
device_code	pointer to i2rest_string structure	i2rest_string structure to save returned device_code If passed, and "provided" is greater than zero, i2rest_request_authorize will save not more than "provided" bytes of returned device_code into "data" part of i2rest_string. If passed, i2rest_request_authorize will save overall length of returned user_code 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_request_authorize will not save returned device_code
expires_in	pointer to int value	Pointer to int value to save returned expires_in parameter If passed, i2rest_request_authorize will save value of returned expires_in parameter into the integer variable pointed by expires_in	Null. i2rest_request_authorize will not save returned expires_in
interval	pointer to int value	Pointer to int value to save returned interval parameter If passed, i2rest_request_authorize will save value of returned interval parameter into the integer variable pointed by interval	Null. i2rest_request_authorize will not save returned interval
auth_url	pointer to zero-terminated string	REQUIRED. Authentication endpoint i2rest_request_authorize will send device code request to this URL. It can start from http://, https:// or file:// prefix
client_id	pointer to zero-terminated string	REQUIRED. Value of client_id i2rest_request_authorize will use this client identifier in device code request.
client_pw	pointer to zero-terminated string	REQUIRED. Value of client_secret i2rest_request_authorize will use this client secret in device code request.
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	Required. Name of IFS file to log received messages Use this parameter for logging responses. Empty string means no logging	Null
sent_log	pointer to zero terminated string	Required. Name of IFS file to log sent messages Use this parameter for logging requests. Empty string means no logging	Null
error_code	pointer to Qus_EC_t structure	error_code parameter If NOT passed (NULL/*Null), i2rest_request_authorize will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint. If passed, i2rest_request_authorize will set standard Qus_EC_t structure with details of unrecoverable errors.	Null

Return parameter

i2rest_request_authorize returns integer value of HTTP response status (values greater than 200), or negative values indicating unrecoverable error, and set error_code parameter:

I2R0002 Bad request parameters. client_id, client_secret, authorization_endpoint should not be empty
I2R0003 Unable to get device_code. Secondary level error text will contain the reason of the error
I2R0004 Unable to initialize secured connection

Difference between revisions of "I2Rest Client API"

Revision as of 15:34, 4 September 2020

Contents

i2Rest Client API functions

Common structures

i2rest_string

C definition and usage

RPGLE definition and usage

i2rest_payload

C definition and usage

RPGLE definition and usage

i2rest_header

C definition and usage

RPGLE definition and usage

Qus_EC_t

C definition and usage

RPGLE definition and usage

i2rest_POST_data

C prototype

RPGLE prototype

Parameters description

Return parameter

i2rest_request_authorize

C prototype

RPGLE prototype

Parameters description

Return parameter

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools