Programmatic interaction via the API between 2 different Falcon instances

In this article, we will show how you can configure data processing between 2 different systems via the API. 

One system will send a request through the outgoing API request mechanism, and the second system will accept this request through the incoming API and process the transmitted data. 

As an example, let's take the task of creating a bug - there is a form on demo solutions that allows you to create a description of the error. This data goes to our task and bug tracking system and a bug is created there based on this external request.

Incoming API on the task and bug tracking system

On the receiving side, we create an incoming API method in the section /asapi: 

Creating a stored procedure for processing this method: 

CREATE PROCEDURE [dbo].[api_bug_newbug]
@parameters ExtendedDictionaryParameter READONLY,
@username nvarchar(256)
as
begin
	declare @type nvarchar(max) = ''
	select @type = Value2 from @parameters where [Key] = 'type'

    declare @text nvarchar(max) = ''
	select @text = Value2 from @parameters where [Key] = 'text'

    declare @info nvarchar(max) = ''
	select @info = Value2 from @parameters where [Key] = 'info'

    declare @g nvarchar(max) = ''
	select @g = Value2 from @parameters where [Key] = 'g'


    declare @projectID int
    select @projectID = id from tt_projects where bugGuid = @g


	if(@projectID is null) begin
    	select 'Wrong BugGuid' Msg, 0 Result, 0 errorCode
    	return
    end

    if(len(@text)>1023) set @text  = substring(@text, 1, 1024)
    if(len(@info)>1023) set @info  = substring(@info, 1, 1024)

    insert into tt_bugs
    	(screen, url, text, description,
         projectID, created, createdBy, statusID)
    values('', '', isnull(@type, '') + '  ' +  isnull(@text, ''),  isnull(@info, ''),
          @projectID, getdate(), '', 1)


    select '' Msg, 1 Result, 0 errorCode
	select 1
	select 'notification' type,
    	'New bug on the API-watch' text ,
        'someuser' [to],
        'common' typeCode,
        '' url,
        '' additional

end
	

Outgoing API request from the demo solution

Creating an outgoing API request method: 

We specify the Request procedure - preparing the request for sending: 

CREATE PROCEDURE [dbo].[api_sendBug_request]
	@parameters ExtendedDictionaryParameter READONLY,  -- incoming parameters for internal processing (use Key, Value2)
	@username nvarchar(32)  -- current user.
AS
BEGIN
	declare @type nvarchar(max) = ''
    select @type   = value2 from @parameters where [key]='type'
    declare @text nvarchar(max) = ''
    select @text   = value2 from @parameters where [key]='text'
    declare @info nvarchar(max) = ''
    select @info   = value2 from @parameters where [key]='info'

    declare @bugGuid nvarchar(max) = ''
    select @bugGuid   = value2 from @parameters where [key]='bugGuid'


	-- SELECT 1  Msg, Result, Url (the address where the request will go)
	select '' Msg, 1 Result, 'https://site.ru/api/action/newbug?g='+@bugGuid+'&text='+@text+'&info='+@info+'&type='+@type Url

	-- SELECT 2 PARAMETERS - parameters that will be passed to an external source
	select 'id' name, '5' value, '' [type] -- form (in the form is passed), header (in http headers), get send requests directly to the URL
END

We prescribe the Response procedure-processing the response from the API source after executing the request: 

CREATE PROCEDURE [dbo].[api_sendBug_response]
	@response nvarchar(max),
	@parameters ExtendedDictionaryParameter READONLY,  -- incoming parameters for internal processing (use Key, Value2 - the same as on request)
	@username nvarchar(32)
AS
BEGIN
	-- SELECT 1
	select '' Msg, 1 Result, @response Response
	-- SELECT 2 External actions
END

In the form where the bug is saved to saveItem through an external action, we will call this action in SELECT 2: 

-- SELECT 2 в SaveItem
select 'apirequest' type,
	'sendBug' code, 'type' p1_name, @ptype p1_value, 'text' p2_name, @ptext p2_value,
	'info' p3_name, @pdata p3_value, 'bugGuid' p4_name, @bugGuid p4_value

Thus, data transfer from one system to another via the universal API mechanism is configured. 

The security of data processing in this case is ensured by using bugguide - if this API is incorrect, it will simply discard the data and not create a bug in the corresponding project. 

An alternative option is to use the API with a Token, when first there is an auth request to get a token, and then the main request is executed.

In this case, the procedure would be somewhat more complicated - it would be necessary to call an additional method in the Response procedure through an external action.

This approach allows you to organize an active dense interaction between different instances of Falcon Space without the need to directly get into the database of another instance. 

Documentation about the Falcon Space Web platform API