API endpoints with sockets

API calls exceeding one minute will result in a timeout. To address this, we have introduced a socket connection mechanism.

Here's the refined explanation of the process:

1. Client Initiation: To begin, the client initiates a room specifically designated for the given tenant-ID and project-ID.
   
2. API Request Dispatch: The client proceeds to dispatch the API request to the server. This request, importantly, promptly concludes without delay.
   
3. Server Processing: Upon receiving the request, the server begins processing the request to generate the desired content. As soon as this task is completed, the server communicates via the socket to provide instructions on how to retrieve the generated information.
   
4. Data Retrieval: The client, now informed by the server via the socket, proceeds to download the generated content. Once this operation is successfully completed, the client gracefully exits the designated room.

Supported API calls

Refer to the API documentation that is released with your server.

Endpoint	Join room event name	Event to connect	Leave room event name
/api/projects/{projectId}/process/targets	joinProcessRoom	process_export_target	leaveProcessRoom
/api/projects/{projectId}/process/sources	joinProcessRoom	process_export_source	leaveProcessRoom
/api/projects/{projectId}/process/pseudo	joinProcessRoom	process_export_pseudo	leaveProcessRoom

returnZip query parameter

The "process"-API calls support a synchronous version (i.e. no use of sockets).

Setting the query parameter returnZip for these calls to true will return the ZIP file.

Sample code

C#

This example below shows C# pseudo-code and uses the SocketIOClient. It contains of a RigiSocket-class, and shows how to use it.

1. using SocketIOClient;
   
2. using System;
   
3. using System.Dynamic;
4. using System.Text.Json;
   
5. using System.Threading;
   

1. public class RigiSocket
   
2. {
   
3.   public RigiSocket(...)
   
4.   {
5.       dynamic dynamicObject = new ExpandoObject();
6.       dynamicObject.token = <token>;
7.       dynamicObject.withCredentials = true;
8.       SocketIOOptions options = new SocketIOOptions
9.       {
10.         Auth = dynamicObject,
11.         Transport = SocketIOClient.Transport.TransportProtocol.WebSocket
12.       };
13.       _client = new SocketIOClient.SocketIO("https://<servername>.rigi.io", options);
14. 
    
15.       _client.OnConnected += async (sender, e) =>
16.       {
17.         dynamic enterRoomObject = new ExpandoObject();
18.         enterRoomObject.projectId = <projectId>;
19.         enterRoomObject.tenantId = <servername>_rigi_io; //Same as the server name, where dots are replaced with underscores
20. 
    
21.         await _client.EmitAsync(<enterRoomEventName>, enterRoomObject);
    
22.       };
23. 
    
24.       _client.On(downloadReadyEvent, response =>
25.       {
26.         //The response was received from the server with the download id.
27.         try
28.         {
29.           using (JsonDocument doc = JsonDocument.Parse(response.ToString()))
30.           {
31.             JsonElement root = doc.RootElement;
32.             _downloadId = root[0].GetProperty("downloadId").GetString();
33.           }
34.         }
35.         catch(Exception e)
36.         {
37.           _downloadId = $"ERROR: {e.Message}";
38.         }
39.       });
40.       _client.ConnectAsync().GetAwaiter().GetResult();
41.     }
42. 
    
43.    private void LeaveRoom()
44.     {
45.       _client.EmitAsync(<leaveRoomEventName>, _projectId).GetAwaiter().GetResult();
46.     }
47. 
    
48.     public static string WaitForDownload(RigiSocket socket, int intervalMs=1000)
49.     {
50.       while (socket._downloadId == null)
51.         Thread.Sleep(intervalMs);
52.       socket.LeaveRoom();
53.       int id;
54.       if (!int.TryParse(socket._downloadId, out id))
55.       {
56.         Console.WriteLine(socket._downloadId); //The download was not successful (the download ID contains the error message)
57.         return null;
58.       }
59.       return socket._downloadId;
60.     }
61.   }
    
62. }


The main program that uses the socket looks like this:

1. var socket = new RigiSocket(...);
   
2. api.execute("api/process/targets", targetfolder, ...);
   
3. string zipId = RigiSocket.WaitForDownload(socket);
4. string generated = pseudoTask.DownloadZipId(zipId); //The ZIP is now in the target folder

• Related Articles

• Example - using the API to clone a project and replace the files

  The Rigi API provides functionalities to create a project based on another project. This may be handy if you need to create Rigi projects on a regular basis, that all have more or less the same settings as an existing project. The only difference is ...