Difference between revisions of "I2Rest Client API"
Pavel.lobko (talk | contribs) (→Simple requests) |
Pavel.lobko (talk | contribs) (→Device code flow) |
||
| Line 27: | Line 27: | ||
:b) value of variables ver_url, ver_url_l, user_code are to be displayed to the end user. | :b) value of variables ver_url, ver_url_l, user_code are to be displayed to the end user. | ||
:c) call to [[#i2rest_wait_authorization | i2rest_wait_authorization API ]] to start polling request authorization sever with device_code (obtained during step a) for token (and refresh token). | :c) call to [[#i2rest_wait_authorization | i2rest_wait_authorization API ]] to start polling request authorization sever with device_code (obtained during step a) for token (and refresh token). | ||
| − | With authorization token obtained in token variable, authorized http request | + | With authorization token obtained in token variable, authorized http request can be performed using i2rest_POST_data. |
==Authorization code flow using i2Rest bridge mode== | ==Authorization code flow using i2Rest bridge mode== | ||
Revision as of 09:59, 10 September 2020
Contents
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 Authorization code flow in i2Rest Bridge mode)
- i2rest_wait_authorization. Get OAuth2 token - last step of OAuth2 Device code flow) or Access token - second step of Authorization code flow in i2Rest Bridge mode
- i2rest_get_access_token. Get Access token (last step of OAuth2 Authorization code flow in i2Rest Bridge mode)
- i2rest_get_fresh_token. Present refresh token and exchange it to new access and refresh token (OAuth2 Refresh token flow)
- 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
Usage scenarios
Simple requests
i2rest_POST_data API composes and performs HTTP/HTTPS request to web resources. Request could have any type (POST, GET, PUT, DELETE), contain additional headers or request body. Provided with oAuth2 token or basic authentification data request could have access to protected resources.
Device code flow
To perform the Device code flow using i2Rest Client API, the following steps must be performed sequentially:
- a) call to i2rest_request_authorize API to obtain user code, device code and verification url(s) from authorization sever.
- b) value of variables ver_url, ver_url_l, user_code are to be displayed to the end user.
- c) call to i2rest_wait_authorization API to start polling request authorization sever with device_code (obtained during step a) for token (and refresh token).
With authorization token obtained in token variable, authorized http request can be performed using i2rest_POST_data.
Authorization code flow using i2Rest bridge mode
Refresh code flow
Client credentials flow
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. |
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:
|
|
| 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. |
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. |
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 |
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 |
|
| 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 |
|
| 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. |
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. |
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. |
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. |
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. |
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. |
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. |
|
| scope | pointer to zero terminated string | OAuth2 scope i2rest_request_authorize will initiate flow for requesting token with this scope(s). Individual scopes should be separated by space |
Null |
| 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. |
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
i2rest_request_bridge_authorize
This function is used at the first step of OAuth2 Authorization Code using i2Rest Bridge mode, to obtain bridge user code, bridge device code and bridge verification url(s).
C prototype
int i2rest_request_bridge_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 bridge user code
i2rest_string *device_code, // input/output - pointer to i2rest_string to save bridge 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 *bridge_url, // input - pointer to bridge endpoint value (zero-terminated string)
char *bridge_cl, // input - pointer to bridge client id (zero-terminated string)
char *bridge_pw, // input - pointer to bridge client secret (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_bridge_authorize...
D PR 10I 0 extproc('i2rest_request_bridge_autho-Return code
D rize')
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 bridge user_code (pointer to i2rest_string)
D device_code * Value bridge 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 bridge_url * Value Options(*String) Bridge URL (z-terminated)
D bridge_cl * Value Options(*String) Bridge client (z-terminated)
D bridge_pw * Value Options(*String) Bridge client secret (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. |
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_bridge_authorize will save not more than "provided" bytes of returned verification_url into "data" part of i2rest_string. |
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_bridge_authorize will save not more than "provided" bytes of returned verification_url_complete into "data" part of i2rest_string. |
Null. i2rest_request_bridge_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_bridge_authorize will save not more than "provided" bytes of returned user_code into "data" part of i2rest_string. |
Null. i2rest_request_bridge_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_bridge_authorize will save not more than "provided" bytes of returned device_code into "data" part of i2rest_string. |
Null. i2rest_request_bridge_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_bridge_authorize will save value of returned expires_in parameter into the integer variable pointed by expires_in |
Null. i2rest_request_bridge_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_bridge_authorize will save value of returned interval parameter into the integer variable pointed by interval |
Null. i2rest_request_bridge_authorize will not save returned interval |
| auth_url | pointer to zero-terminated string | REQUIRED. Authentication endpoint
i2rest_request_bridge_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_bridge_authorize will use this client identifier in device code request. |
|
| client_pw | pointer to zero-terminated string | REQUIRED. Value of client_secret
i2rest_request_bridge_authorize will use this client secret in device code request. |
|
| scope | pointer to zero terminated string | OAuth2 scope i2rest_request_bridge_authorize will initiate flow for requesting token with this scope(s). Individual scopes should be separated by space |
Null |
| bridge_url | pointer to zero terminated string | REQUIRED. Bridge endpoint i2Rest Bridge endpoint. See details at Authorization Code flow using i2Rest bridge mode |
|
| bridge_cl | pointer to zero terminated string | REQUIRED. Bridge client ID See details at Authorization Code flow using i2Rest bridge mode |
|
| bridge_pw | pointer to zero terminated string | REQUIRED. Bridge client secret See details at Authorization Code flow using i2Rest bridge mode |
|
| 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_bridge_authorize will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint. |
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
i2rest_wait_authorization
This function is used at the last step of Device code flow - to get device access token, or as the second step of Authorization Code flow using i2Rest Bridge mode - to get Access code.
C prototype
int i2rest_wait_authorization(void **p_handler, // pointer to request handler, input/output
int *status, // output - pointer to place where response status should be stored
i2rest_string *token, // input/output - pointer to i2rest_string
// to save token (device code flow) or access code (bridge mode)
i2rest_string *r_token, // input/output - pointer to i2rest_string
// to save refresh token (device code flow)
i2rest_string *scope, // input/output - pointer to i2rest_string
// returned token scope (device code flow)
i2rest_string *token_type, // input/output - pointer to i2rest_string
// returned token type (device code flow)
int *expires_in, // output - pointer to int value. Expiration time for device and user codes
i2rest_string *device_code, // input - pointer to i2rest_string
// that contains value of device_code that was received at i2rest_request_authorize
// or i2rest_request_bridge_authorize
char *token_url, // input - pointer to token or bridge 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 *grant_type, // input - device code flow: "urn:ietf:params:oauth:grant-type:device_code",
// bridge: "urn:i2rest:bridge:access_code"
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_wait_authorization...
D PR 10I 0 extproc('i2rest_wait_authorization') Return code
D p_handler * Pointer to void pointer
D status * Value status (pointer to int)
D token * Value token/access code (pointer to i2rest_string)
D r_token * Value refresh_token (pointer to i2rest_string)
D scope * Value scope (pointer to i2rest_string)
D token_type * Value token_type (pointer to i2rest_string)
D expires_in * Value expires_in (pointer to int)
D device_code * Value device_code (pointer to i2rest_string)
D token_url * Value Options(*String) Token/bridge endpoint (z-terminated)
D client_id * Value Options(*String) client_id (z-terminated)
D client_pw * Value Options(*String) client_secret (z-terminated)
D grant_type * Value Options(*String) grant_type (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. |
Null (temporary API handler will be created) |
| status | pointer to int value | Pointer to int value to store completion status If passed, i2rest_wait_authorize will store completion status to integer value pointed by this parameter:
|
Null |
| token | pointer to i2rest_string structure | i2rest_string structure to save returned token/access code value If passed, and "provided" is greater than zero, i2rest_wait_authorize will save not more than "provided" bytes of returned token/access code into "data" part of i2rest_string. |
Null. i2rest_wait_authorize will not save returned token/access code |
| r_token | pointer to i2rest_string structure | i2rest_string structure to save returned refresh token value (Device code flow only) If passed, and "provided" is greater than zero, i2rest_wait_authorize will save not more than "provided" bytes of returned refresh token into "data" part of i2rest_string. |
Null. i2rest_wait_authorize will not save returned refresh token |
| scope | pointer to i2rest_string structure | i2rest_string structure to save returned token scope value (Device code flow only) If passed, and "provided" is greater than zero, i2rest_wait_authorize will save not more than "provided" bytes of returned token scope into "data" part of i2rest_string. |
Null. i2rest_wait_authorize will not save returned token scope |
| token_type | pointer to i2rest_string structure | i2rest_string structure to save returned token type value (Device code flow only) If passed, and "provided" is greater than zero, i2rest_wait_authorize will save not more than "provided" bytes of returned token type into "data" part of i2rest_string. |
Null. i2rest_wait_authorize will not save returned token type |
| expires_in | pointer to int value | Pointer to int value to save returned expires_in parameter If passed, i2rest_wait_authorize will save value of returned expires_in parameter into the integer variable pointed by expires_in |
Null. i2rest_wait_authorize will not save returned expires_in |
| device_code | pointer to i2rest_string structure | REQUIRED. i2rest_string structure containing device_code or bridge device code This field should contain the value of device_code (Device code flow) or bridge device code (Authorization code flow using bridge mode). i2rest_wait_authorize will use minimal value from "provided" and "available" as meaning length of "data" part as device_code or bridge device code value |
|
| token_url | pointer to zero-terminated string | REQUIRED. Token/bridge endpoint
i2rest_wait_authorize will send request to this URL |
|
| client_id | pointer to zero-terminated string | REQUIRED. Value of client_id
i2rest_wait_authorize will use this client identifier in request. |
|
| client_pw | pointer to zero-terminated string | REQUIRED. Value of client_secret
i2rest_wait_authorize will use this client secret in request. |
|
| grant_type | pointer to zero terminated string | REQUIRED. Grant type One of:
|
|
| 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 |
|
| 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 |
|
| error_code | pointer to Qus_EC_t structure | error_code parameter If NOT passed (NULL/*Null), i2rest_wait_authorize will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint. |
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:
- I2R0004 Unable to initialize secured connection
- I2R0005 Unable to get authorization token. Secondary level error text will contain the reason of the error
- I2R0006 Bad request parameters. client_id, client_secret, token_endpoint should not be empty
i2rest_get_access_token
This function is used at the last step of Authorization code flow using i2Rest bridge mode - to get access token. It is required to obtain access code using i2rest_wait_authorization and send it to the token endpoint
C prototype
int i2rest_get_access_token(void **p_handler, // pointer to request handler, input/output
i2rest_string *token, // input/output - pointer to i2rest_string
// to save token
i2rest_string *r_token, // input/output - pointer to i2rest_string
// to save refresh token
i2rest_string *scope, // input/output - pointer to i2rest_string
// returned token scope
i2rest_string *token_type, // input/output - pointer to i2rest_string
// returned token type
int *expires_in, // output - pointer to int value. Token expiration time
char *token_url, // input - pointer to token endpoint (zero-terminated string)
char *bridge_url, // input - pointer to bridge 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)
i2rest_string *access_code, // input - pointer to i2rest_string
// that contains access code (got by i2rest_wait_authorization)
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_get_access_token...
D PR 10I 0 extproc('i2rest_get_access_token') Return code
D p_handler * Pointer to void pointer
D token * Value token/access code (pointer to i2rest_string)
D r_token * Value refresh_token (pointer to i2rest_string)
D scope * Value scope (pointer to i2rest_string)
D token_type * Value token_type (pointer to i2rest_string)
D expires_in * Value expires_in (pointer to int)
D token_url * Value Options(*String) Token endpoint (z-terminated)
D bridge_url * Value Options(*String) Bridge endpoint (z-terminated)
D client_id * Value Options(*String) client_id (z-terminated)
D client_pw * Value Options(*String) client_secret (z-terminated)
D access_code * Value access code (pointer to i2rest_string)
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. |
Null (temporary API handler will be created) |
| token | pointer to i2rest_string structure | i2rest_string structure to save returned token value If passed, and "provided" is greater than zero, i2rest_get_access_token will save not more than "provided" bytes of returned token into "data" part of i2rest_string. |
Null. i2rest_wait_authorize will not save returned token |
| r_token | pointer to i2rest_string structure | i2rest_string structure to save returned refresh token value If passed, and "provided" is greater than zero, i2rest_get_access_token will save not more than "provided" bytes of returned refresh token into "data" part of i2rest_string. |
Null. i2rest_get_access_token will not save returned refresh token |
| scope | pointer to i2rest_string structure | i2rest_string structure to save returned token scope value If passed, and "provided" is greater than zero, i2rest_get_access_token will save not more than "provided" bytes of returned token scope into "data" part of i2rest_string. |
Null. i2rest_get_access_token will not save returned token scope |
| token_type | pointer to i2rest_string structure | i2rest_string structure to save returned token type value If passed, and "provided" is greater than zero, i2rest_get_access_token will save not more than "provided" bytes of returned token type into "data" part of i2rest_string. |
Null. i2rest_get_access_token will not save returned token type |
| expires_in | pointer to int value | Pointer to int value to save returned expires_in parameter If passed, i2rest_get_access_token will save value of returned expires_in parameter into the integer variable pointed by expires_in |
Null. i2rest_get_access_token will not save returned expires_in |
| token_url | pointer to zero-terminated string | REQUIRED. Token endpoint
i2rest_get_access_token will send request to this URL |
|
| bridge_url | pointer to zero-terminated string | REQUIRED. Bridge endpoint
i2rest_get_access_token will use this value as "redirect_uri" parameter of the request to the token endpoint |
|
| client_id | pointer to zero-terminated string | REQUIRED. Value of client_id
i2rest_get_access_token will use this client identifier in request. |
|
| client_pw | pointer to zero-terminated string | REQUIRED. Value of client_secret
i2rest_get_access_token will use this client secret in request. | |
| access_code | pointer to i2rest_string structure | REQUIRED. i2rest_string structure containing access_code This field should contain the value of access_code that was received in i2rest_wait_authorize. |
|
| 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 |
|
| 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 |
|
| error_code | pointer to Qus_EC_t structure | error_code parameter If NOT passed (NULL/*Null), i2rest_get_access_token will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint. |
Null |
Return parameter
i2rest_get_access_token returns integer value of HTTP response status (values greater than 200), or negative values indicating unrecoverable error, and set error_code parameter:
- I2R0004 Unable to initialize secured connection
- I2R0009 Unable to get fresh authorization token. Secondary level error text will contain the reason of the error
- I2R0010 Bad request parameters. client_id, client_pw, token_url and bridge_url should not be empty
i2rest_get_fresh_token
This function is used at the Refresh token flow - to present refresh token and get new access token.
C prototype
int i2rest_get_fresh_token(void **p_handler, // pointer to request handler, input/output
i2rest_string *token, // input/output - pointer to i2rest_string
// to save token
i2rest_string *r_token, // input/output - pointer to i2rest_string
// to save refresh token
i2rest_string *scope, // input/output - pointer to i2rest_string
// returned token scope
i2rest_string *token_type, // input/output - pointer to i2rest_string
// returned token type
int *expires_in, // output - pointer to int value. Token expiration time
char *token_url, // input - pointer to token 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)
i2rest_string *o_token, // input - pointer to i2rest_string
// that contains current value of refresh token
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_get_fresh_token...
D PR 10I 0 extproc('i2rest_get_fresh_token') Return code
D p_handler * Pointer to void pointer
D token * Value token/access code (pointer to i2rest_string)
D r_token * Value refresh_token (pointer to i2rest_string)
D scope * Value scope (pointer to i2rest_string)
D token_type * Value token_type (pointer to i2rest_string)
D expires_in * Value expires_in (pointer to int)
D token_url * Value Options(*String) Token endpoint (z-terminated)
D client_id * Value Options(*String) client_id (z-terminated)
D client_pw * Value Options(*String) client_secret (z-terminated)
D o_token * Value old refresh token (pointer to i2rest_string)
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. |
Null (temporary API handler will be created) |
| token | pointer to i2rest_string structure | i2rest_string structure to save returned token value If passed, and "provided" is greater than zero, i2rest_get_fresh_token will save not more than "provided" bytes of returned token into "data" part of i2rest_string. |
Null. i2rest_get_fresh_token will not save returned token |
| r_token | pointer to i2rest_string structure | i2rest_string structure to save returned refresh token value If passed, and "provided" is greater than zero, i2rest_get_fresh_token will save not more than "provided" bytes of returned new refresh token into "data" part of i2rest_string. |
Null. i2rest_get_fresh_token will not save returned new refresh token |
| scope | pointer to i2rest_string structure | i2rest_string structure to save returned token scope value If passed, and "provided" is greater than zero, i2rest_get_fresh_token will save not more than "provided" bytes of returned token scope into "data" part of i2rest_string. |
Null. i2rest_get_fresh_token will not save returned token scope |
| token_type | pointer to i2rest_string structure | i2rest_string structure to save returned token type value If passed, and "provided" is greater than zero, i2rest_get_access_token will save not more than "provided" bytes of returned token type into "data" part of i2rest_string. |
Null. i2rest_get_fresh_token will not save returned token type |
| expires_in | pointer to int value | Pointer to int value to save returned expires_in parameter If passed, i2rest_get_fresh_token will save value of returned expires_in parameter into the integer variable pointed by expires_in |
Null. i2rest_get_fresh_token will not save returned expires_in |
| token_url | pointer to zero-terminated string | REQUIRED. Token endpoint
i2rest_get_fresh_token will send request to this URL |
|
| client_id | pointer to zero-terminated string | REQUIRED. Value of client_id
i2rest_get_fresh_token will use this client identifier in request. |
|
| client_pw | pointer to zero-terminated string | REQUIRED. Value of client_secret
i2rest_get_fresh_token will use this client secret in request. | |
| o_token | pointer to i2rest_string structure | REQUIRED. i2rest_string structure containing old refresh token This field should contain the old value of refresh_token. |
|
| 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 |
|
| 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 |
|
| error_code | pointer to Qus_EC_t structure | error_code parameter If NOT passed (NULL/*Null), i2rest_get_fresh_token will throw exception messages on unrecoverable errors. Unrecoverable errors are different from protocol errors, returned by the API endpoint. |
Null |
Return parameter
i2rest_get_fresh_token returns integer value of HTTP response status (values greater than 200), or negative values indicating unrecoverable error, and set error_code parameter:
- I2R0004 Unable to initialize secured connection
- I2R0009 Unable to get fresh authorization token. Secondary level error text will contain the reason of the error
- I2R0010 Bad request parameters. client_id, client_pw, token_url and bridge_url should not be empty
