Introduction & Setup

This article introduces the Gimmal Physical REST Services, touching on common topics for the use and setup of the API.

Service URLs

You will need the correct URLs for accessing Gimmal Physical. For Gimmal Cloud-hosted environments:

Component	URL Pattern
Application URL	`https://<hostname>.gimmal.com/`
REST Web Service URL	`https://<hostname>-services.gimmal.com`

For on-premises installations:

CODE

http(s)://[ServerName]:[PortID]/api

Authentication

All endpoints require authentication (except /api/Test). Supported methods:

Method	Header Format
Basic Authentication	`Authorization: Basic <base64(username:password)>`
Bearer Token	`Authorization: Bearer <token>`
HMAC	Per HMAC specification
Certificate	Client certificate in TLS handshake

All examples in this guide use Basic Authentication.

Common Request Header Example

CODE

Content-Type:  application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Every POST, PUT, and DELETE request with a body must include the Content-Type: application/json header. Omitting it produces a "media type not supported" error.

Swagger Documentation

The Swagger page provides definitions for methods in the REST calls and can be accessed without authentication:

CODE

https://<hostname>-services.gimmal.com/swagger

CORS & Security

CORS is enabled with SupportsCredentials = true. Role-based security can be toggled via the API_SECURITY_KEY setting in APPLICATION_CONFIGURATION. When enabled, users only see items they have rights to access.

Production Requirement: Always use HTTPS in production. Never hard-code credentials in source code — use environment variables or a secure vault.

The great majority of API deployments will not be using user based security

Connection Test

GET /api/Test

Tests the connection to Gimmal Physical Web Services. No authentication required. A successful response returns: "Successfully connected to InfolinxRest"

CODE

GET "http://your-server/api/Test"

Tip: Use this endpoint first when setting up a new integration to confirm network connectivity and that the REST service is running.

C# SetHeaders Helper

Official Gimmal C# samples reference this helper method. Replace [USERNAME] and [PASSWORD] with your credentials.

CODE

void SetHeaders(HttpWebRequest webRequest, string method, string body)
{
  webRequest.Method = method;
  webRequest.Credentials = new NetworkCredential("[USERNAME]", "[PASSWORD]");
  webRequest.PreAuthenticate = true;
  webRequest.AllowWriteStreamBuffering = true;
  if (method == "POST" || method == "PUT")
  {
    webRequest.ContentType = "application/json";
    webRequest.ContentLength = body.Length;
    try
    {
      StreamWriter sw = new StreamWriter(webRequest.GetRequestStream());
      sw.Write(body);
      sw.Close();
    }
    catch (Exception ex) { }
  }
}