REST API Endpoint Configuration in R-COM Gateway

The REST API is the one of the data ingestion channel for R-COM Gateway, enabling seamless, on-demand communication between external systems and the platform. This guide provides the technical specifications and step-by-step procedures required to configure, secure, and test API endpoints for enterprise integration.

Where to Begin

From the R-COM Gateway dashboard, Go to:

• Integrations > REST API

From this interface, you can manage the lifecycle of your endpoints:

• View endpoints: Open the endpoints configured for an API route.
• Edit/Delete: Modify active routes or remove deprecated interfaces.
• Create: Define a route and its endpoints with Create API Route.
• Copy Base URL: Copy the client base URL for use when constructing endpoint URLs.
• Open API documentation or Copy Swagger Link: Open or share the generated API documentation.

REST API endpoints

To create one, select Create API Route.

---

Step 1: Define the API Endpoint (Base Configuration)

An API Route is a logical container for related endpoints. It defines the base route path and global enabled state for all endpoints configured within it.

Configure new API endpoint

Configuration Fields

Field	Description
Route name	Unique internal identifier (e.g., Logistics_Ingest).
Base Route Path	Starting point of your URL (e.g., /RCOMENDPOINTAPI/inventory). Must start with a letter and use only alphanumeric characters or underscores ( _ ).
Route enabled	Globally enables or disables all endpoints under this API route.

warning

Mandatory URL Structure: All R-COM Gateway URLs must include the RCOMENDPOINTAPI segment.
Example:

https://rcom-gateway.example.com/RCOMENDPOINTAPI/inventory

---

Step 2: Configure Individual Routes

Each endpoint defines how a specific kind of data is handled under the API Route. You can add multiple endpoints for different purposes.

Select Add Endpoint and configure:

Route Configuration Fields

Field	Description
Endpoint Name	The final segment of the URL (e.g., productScanPost, stockUpdateGet).
Event Type	Defines how R-COM Gateway processes incoming data: - AllData: Generic payloads - CustomTrigger: Special format used inside gateway - EpcisMessage, EpcisObject: EPCIS-compliant data - GhostData: Used for communication between RcomMobile and Gateway - UHFTagRead: RFID tag scan events
HTTP method	HTTP method (GET or POST) used by the endpoint.
Authentication	Security method: NoAuth, Bearer/Access Token, or Basic. Basic uses mapped Basic Auth accounts. Bearer/Access Token uses roles associated with Access Tokens or an authenticated user's bearer token.
Authorized Roles	Roles permitted to call an endpoint that uses Bearer/Access Token authentication.
Payload format	Defines how R-COM Gateway interprets the data structure and is normally populated from the Event Type.
Process asynchronously	When enabled, processing continues in the background and the caller does not wait for the workflow result.
Request timeout (ms)	Maximum time the Gateway waits for a synchronous request to complete. This setting is available when Process asynchronously is not enabled.

warning

Routes must be unique across the entire client. A route name can only be used once in the gateway and cannot be reused in any other endpoint configurations.

When to use Sync/Async API

Feature	Synchronous	Asynchronous
Best For	Real-time validation, status queries.	High-volume uploads, bulk telemetry.
Client Experience	Waits for processing completion.	Receives instant acknowledgment.
HTTP Success	200 OK	202 Accepted

info

For the shown example, this defines a full route at:

POST https://rcom-gateway.example.com/RCOMENDPOINTAPI/inventory/productScanPost

---

Adding Multiple Routes

You can define multiple routes under the same API Endpoint, allowing modular, RESTful behavior under a shared namespace.

Route Path	Purpose
/RCOMENDPOINTAPI/inventory/productScanPost	Accepts barcode/RFID scan data
/RCOMENDPOINTAPI/inventory/update	Update product stock levels
/RCOMENDPOINTAPI/inventory/status	Query the current inventory

Use Add Endpoint to add more handlers.

---

Step 3: Publish Routes

Once you’ve filled out all fields, select Save. If Route enabled is active, the API route is ready to receive data.

Publish new API endpoint

Sync Routes

Use Sync routes from API source when the routes provided by the API source need to be synchronized with the Gateway. Select Sync routes from API source, then select Sync now in the Sync Endpoints? dialog.

warning

Endpoints can be temporarily unavailable while routes are synchronized. Perform the synchronization during an appropriate maintenance window or notify API consumers before starting it.

---

HTTP Method Behavior in R-COM Gateway

HttpPost (Receive Data)

This method is used when external systems send data into R-COM Gateway.

• The data (typically JSON) is included in the body of the request.
• R-COM Gateway processes this payload according to the Route's configuration.

tip

✅ Use when external clients or devices need to push scanned tags, inventory updates, or sensor readings into R-COM Gateway.

Example:

POST /RCOMENDPOINTAPI/inventory/scan

Body:

{
  "deviceId": "scanner-001",
  "barcode": "1234567890",
  "timestamp": "2025-05-27T10:15:00Z"
}

---

HttpGet (Respond to Queries)

This method is used when external systems want to request data from R-COM Gateway.

• Parameters are passed via the URL query string.
• The response typically includes a data snapshot or status info.

tip

✅ Use when a client needs to fetch the latest state of an object, verify a tag, or query past events.

Example:

GET /RCOMENDPOINTAPI/inventory/status?productId=123456

---

Testing the Route in Postman

1. Open Postman and create a new request.
2. Method: POST
3. URL:

https://rcom-gateway.example.com/RCOMENDPOINTAPI/inventory/productScanPost

4. Authorization Tab:
   • Type: Bearer Token
   • Token: YOUR_OAUTH_TOKEN if any.
5. Headers Tab:
   • Content-Type: application/json
6. Body Tab:
   • Select: raw + JSON
   • Paste your payload:

{
  "deviceId": "scanner-001",
  "barcode": "1234567890",
  "timestamp": "2025-05-27T10:15:00Z"
}

7. Click Send

✅ A 200 OK or 202 Accepted response confirms the route is working.

---

info

Final Checklist

Before going live:

✅ Confirm your base path and route names follow correct syntax.
✅ Use OAuth2 or Basic auth in production environments.
✅ Validate your payload mappings for each event type.
✅ Test your route using Postman or curl.

Related Articles

• Create Basic Auth Accounts in R-COM Gateway
• Create Access Tokens in R-COM Gateway
• MQTT Client Configuration in R-COM Gateway
• Scheduling Events with Gateway