Skip to main content

Migrating from SOAP to REST

This guide helps you migrate an existing ECGridOS SOAP integration to the ECGrid REST API. The REST API (v2.6) is actively developed and is the recommended path for all new and maintained integrations.

Why Migrate?​

ReasonDetail
REST is the active APINew features, endpoints, and improvements are added to REST only
SOAP is establishedECGridOS v4.1 receives security patches and critical updates only
Simpler authenticationReplace stateful Login() / SessionID with a single X-API-Key header
Standard toolingREST works with any HTTP client, OpenAPI generators, Postman, and curl
JSON vs XMLJSON is lighter and easier to work with in modern .NET
Better error handlingTyped JSON error responses instead of SOAP Faults

Migration Strategy​

A typical SOAP-to-REST migration involves three parallel workstreams:

  1. Authentication — Replace Login() / SessionID with API key or Bearer JWT
  2. Method calls — Map each SOAP method to its REST equivalent endpoint
  3. Data handling — Replace XML deserialization with System.Text.Json

You do not need to migrate everything at once. The two APIs are independent — you can migrate one workflow at a time.

Step 1 — Authentication Migration​

This is the most impactful change. Every SOAP method takes a SessionID as its first parameter. In REST, authentication is a single header on every request.

SOAP — before:

// Must call Login() first; SessionID required on every method
var sessionID = await client.LoginAsync(email, password);
var mailbox   = await client.MailboxInfoAsync(sessionID, mailboxID);
await client.LogoutAsync(sessionID);

REST — after:

// API key is set once on the HttpClient; no Login/Logout needed
http.DefaultRequestHeaders.Add("X-API-Key", apiKey);
var mailbox = await http.GetFromJsonAsync<ApiResponse<MailboxInfo>>($"/v2/mailboxes/{mailboxID}");

To obtain your API key:

GET /v2/users/{userID}/api-key HTTP/1.1
Host: rest.ecgrid.io
X-API-Key: your-existing-api-key

Or generate a new one:

POST /v2/users/{userID}/generate-api-key HTTP/1.1

Step 2 — Method Mapping​

The table below maps the most commonly used SOAP methods to their REST equivalents.

Authentication​

SOAP MethodREST EndpointNotes
Login()POST /v2/auth/loginOr skip login entirely — use X-API-Key
Logout()POST /v2/auth/logoutNot needed when using API key
WhoAmI()GET /v2/users/me
SessionInfo()POST /v2/auth/session
Version()GET /v2/auth/version

Networks​

SOAP MethodREST EndpointNotes
NetworkInfo()GET /v2/networks/{networkID}
NetworkList()GET /v2/networks
NetworkAdd()POST /v2/networks
NetworkUpdate()PUT /v2/networks/{networkID}

Mailboxes​

SOAP MethodREST EndpointNotes
MailboxInfo()GET /v2/mailboxes/{mailboxID}
MailboxList()GET /v2/mailboxes
MailboxAdd()POST /v2/mailboxes

IDs (Trading Partners)​

SOAP MethodREST EndpointNotes
TPInfo()GET /v2/ids/{ecgridID}
TPList()GET /v2/ids
TPAdd()POST /v2/ids
TPSearch()GET /v2/ids/find
TPMove()POST /v2/ids/{ecgridID}/move-tp

Partners (Interconnects)​

SOAP MethodREST EndpointNotes
InterconnectInfo()GET /v2/partners/{partnerID}
InterconnectAdd()POST /v2/partners
InterconnectList()GET /v2/partners
InterconnectCancel()DELETE /v2/partners/{partnerID}
InterconnectCount()GET /v2/partners/count

Parcels (File Transfer)​

SOAP MethodREST EndpointNotes
ParcelInBox()POST /v2/parcels/inbox-list
ParcelOutBox()POST /v2/parcels/outbox-list
ParcelUpload()POST /v2/parcels/upload
ParcelDownload()POST /v2/parcels/download
ParcelDownloadConfirm()POST /v2/parcels/confirm
ParcelInfo()GET /v2/parcels/{parcelID}
ParcelResend()POST /v2/parcels/{parcelID}/reset-to-inbox
ParcelCancel()POST /v2/parcels/{parcelID}/cancel

Interchanges​

SOAP MethodREST EndpointNotes
InterchangeInBox()POST /v2/interchanges/inbox-list
InterchangeOutBox()POST /v2/interchanges/outbox-list
InterchangeInfo()GET /v2/interchanges/{interchangeID}
InterchangeResend()POST /v2/interchanges/{interchangeID}/resend
InterchangeCancel()POST /v2/interchanges/{interchangeID}/cancel

Users​

SOAP MethodREST EndpointNotes
UserInfo()GET /v2/users/{userID}
UserList()GET /v2/users
UserAdd()POST /v2/users
UserUpdate()PUT /v2/users/{userID}
UserSetAuthLevel()POST /v2/users/{userID}/set-role
UserGetAPIKey()GET /v2/users/{userID}/api-key
UserGenerateAPIKey()POST /v2/users/{userID}/generate-api-key

Step 3 — Data Format Migration​

SOAP returns XML; REST returns JSON. The field names are similar but not identical.

SOAP — XML response (MailboxInfo):

<MailboxInfoResult>
  <MailboxID>12345</MailboxID>
  <MailboxName>My Mailbox</MailboxName>
  <Status>Active</Status>
</MailboxInfoResult>

REST — JSON response (GET /v2/mailboxes/{id}):

{
  "success": true,
  "data": {
    "mailboxID": 12345,
    "mailboxName": "My Mailbox",
    "status": "Active"
  }
}

In .NET 10, use System.Text.Json for deserialization

using System.Net.Http.Json;

// REST — read typed response
var response = await http.GetFromJsonAsync<ApiResponse<MailboxInfo>>($"/v2/mailboxes/{mailboxID}");
var mailbox  = response!.Data;

Before and After — Parcel Download Workflow​

This example shows a complete SOAP workflow and its REST equivalent.

SOAP — before​

// .NET 10 — SOAP parcel download workflow (before migration)
using var client = new ECGridOSPortTypeClient();

var sessionID  = await client.LoginAsync(email, password);
var parcelList = await client.ParcelInBoxAsync(sessionID);

foreach (var parcel in parcelList)
{
    // Download the parcel
    var data = await client.ParcelDownloadAsync(sessionID, parcel.ParcelID);

    // Save to disk
    await File.WriteAllBytesAsync($"{parcel.ParcelID}.edi", data.ParcelBytes);

    // Confirm receipt
    await client.ParcelDownloadConfirmAsync(sessionID, parcel.ParcelID);
}

await client.LogoutAsync(sessionID);

REST — after​

// .NET 10 — REST parcel download workflow (after migration)
// IHttpClientFactory injected via DI; API key pre-configured on the named client

var http = httpClientFactory.CreateClient("ECGrid");

// Step 1 — get the inbox list
var inboxResponse = await http.PostAsJsonAsync("/v2/parcels/pending-inbox-list");

inboxResponse.EnsureSuccessStatusCode();
var inbox = await inboxResponse.Content.ReadFromJsonAsync<ApiResponse<List<ParcelInfo>>>();

foreach (var parcel in inbox!.Data!)
{
    // Step 2 — download
    var downloadResponse = await http.PostAsJsonAsync("/v2/parcels/download",
        new { parcelID = parcel.ParcelID });

    downloadResponse.EnsureSuccessStatusCode();

    var bytes = await downloadResponse.Content.ReadAsByteArrayAsync();
    await File.WriteAllBytesAsync($"{parcel.ParcelID}.edi", bytes);

    // Step 3 — confirm receipt
    await http.PostAsJsonAsync("/v2/parcels/confirm",
        new { parcelID = parcel.ParcelID });
}

Key differences:

  • No Login() / Logout() — API key is set once on the HttpClient
  • JSON bodies instead of strongly-typed proxy parameters
  • Standard HttpResponseMessage error handling instead of SOAP Faults

Error Handling Migration​

SOAP — catch FaultException:

catch (FaultException fault)
{
    Console.Error.WriteLine($"SOAP Fault: {fault.Message}");
}

REST — check HTTP status and parse JSON error:

if (!response.IsSuccessStatusCode)
{
    var error = await response.Content.ReadFromJsonAsync<ApiError>();
    Console.Error.WriteLine($"[{error?.ErrorCode}] {error?.Message}");
}

See Error Handling & Troubleshooting for full patterns.