InHouse EDI API allows you to run EdiNation's EDI translation and validation API in your own cloud or on-prem environment(s).

Concept

The Inhouse API provides the following operations to run in your environment as opposed to running in our cloud:

• Read EDI (parsing X12, EDIFACT, HL7, etc. files)
• Write EDI (generating X12, EDIFACT, HL7, etc. files)
• Validate EDI (validating X12, EDIFACT, HL7, etc. messages)
• Acknowledge EDI (generating TA1, 997, 999 for X12, and CONTRL for EDIFAC)

These, commonly called EDI translation & validation operations, are the only ones from the managed EDI API that require unencrypted EDI files for processing.

The main goals of the Inhouse API are:

• To preserve sensitive EDI data by allowing you to execute all the translation & validation operations on your servers under your control. Your, or your partner's EDI files never leave your network and you don't have to worry about third-party dependencies, SOC2 or HIPAA compliance, or signing BAAs.
• To allow you to ramp up and down infrastructure, cloud or on-prem, when you need it.
• To provide modern, composable building blocks for EDI translation, that can be shared between the teams in your organization.

Difference between the Managed API and the InHouse API

The InHouse API should be substitutable with its managed counterpart so that you are able to switch between the two by simply swapping the URL from one to the other. 

Managed EdiNation EDI API

The Managed edition of the API is hosted in our own Azure cloud subscription. You don't need to install anything in your environments/servers and all EDI translation and validation are carried out on our servers.

To use any of the API methods you need to send your EDI data/files to our servers for processing.

The Managed API also comes with model management operations, which only work with the managed edition.

Inhouse EdiNation EDI API

The In-house edition of the API is hosted in your own cloud or on-prem environments. You need to download and install the API.

All EDI translation and validation operations are carried out in your environment and your sensitive EDI data/files never leave it. You are able to ramp up/down infrastructure when you need it.

None of the model operations are included in the InHouse API and you'll still need access to the Managed API if you want to create or modify custom models. 

The following functionality remains available only in the Managed API:

• Import SEF
• Model management
• Viewing/downloading EDI models

Installation

The Inhouse API is written in .NET 6 (same as the cloud EDI API) and is provided as two DLL files (additionally two NuGet packages are also included):

• EdiFabric.dll
• EdiFabric.Api.dll

The files can be imported from within Visual Studio 2022 to a .NET project, such as ASP .NET Core, Azure Function, or AWS Lambda (using the AWS Toolkit extension for Visual Studio 2022).

The downloadable product bundle is equipped with Visual Studio solutions for Azure Function (isolated), AWS Lambda (with API Gateway), and ASP .NET Core to help you get started with the InHouse API in minutes.

Authentication

To use the InHouse API you need to obtain a valid API key. The API key is delivered to your account in EdiNation, as well as by email after you sign up for a free trial.

Every method of the InHouse API has an API key parameter, where you include your API key.

The API key is sent to an Auth API that sits in our cloud (same as the Managed API). Upon successful validation of the API key, the Auth API returns a token that is valid for 30 days. This means that no more calls to the Auth API will be made for some time. 

A few days before the token expires, another call to the Auth API will be made to refresh the token for another 30 days.

The URL for the Auth API must be set as an environment variable - EDINATION_AUTHAPI_URL.

In order for the InHouse API to successfully retrieve the authentication token, you need to allow external HTTP GET calls to the Auth API, currently accessible at:

https://api.edination.com/v2

Models

The Managed API automatically loads the models corresponding to an EDI type, either automatically or explicitly using the models API. All model management operations are missing from the InHouse API, therefore, models are loaded from the Auth API.

Every time a new model is required, e.g. an X12 837P is read fohttps://api.edination.com/v2r the first time, a call to the Auth API is made to retrieve all models for the X12 HIPAA version and cache them locally in the InHouse API. Models are loaded in .NET's app domain, the same as the authentication token, and remain there until the app domain is unloaded (due to app restart or infrastructure ramping up/down).

To retrieve models from the Auth API, you need to allow external HTTP GET calls to the Auth API. 

As mentioned above, all model operations remain in the Managed API, therefore, if you want to import SEF files, create new models from scratch or modify existing ones, you still need to do this in the Managed API (either via the API or EdiNation).

Custom models are used in the same way as in the managed operation - by supplying the model parameter for the Read operation, and the Model property in the JSON request for the rest of the operations.

API Reference

The provided examples for using the InHouse API as Azure Function, AWS Lambda, and ASP .NET Core to show you how to utilize the API in the same way as the Managed API, adhering to the same EdiNation API Reference and EdiNation API Docs.

In reality, the InHouse EDI API is located in the EdiFabric.Api.dll (or EdiFabric.Api.nupkg) and is a set of .NET services:

• EdifactService
• X12Service
• Hl7Service
• NcpdpService
• VdaService

Each service corresponds to the supported EDI standard, and provides the following methods:

Read EDI

ReadAsync(Stream input, Stream utf8JsonOut, string apiKey, ReadParams rParams)

string ReadAsync(Stream input, string apiKey, ReadParams rParams)

Write EDI

WriteAsync(Stream utf8JsonIn, Stream output, string apiKey, WriteParams wParams)

string WriteAsync(Stream utf8JsonIn, string apiKey, WriteParams wParams)

Validate EDI

ValidateAsync(Stream utf8JsonIn, Stream utf8JsonOut, string apiKey, ValidateParams vParams)

string ValidateAsync(Stream utf8JsonIn, string apiKey, ValidateParams vParams)

Acknowledge EDI - for X12 and EDIFACT only

GenerateAckAsync(Stream utf8JsonIn, Stream utf8JsonOut, string apiKey, AckParams aParams)

string GenerateAckAsync(Stream utf8JsonIn, string apiKey, AckParams aParams)

All methods expect the input to be binary (.NET Stream), regardless of if it's EDI file contents or JSON.

There are two options for the output - either receive it as binary (.NET Stream) or as a string.

All methods are async (return a .NET Task), expect a valid API key, and have an optional set of parameters.

Evaluation

To get started with InHouse API, sign up for a trial, and download the product and Visual Studio examples. The trial is free for 14 days and you can run it on as many environments as you want.

Another way to evaluate the functionality is to simply use the Managed API. Switching from the Managed API to the InHouse is seamless.

License and service terms

You can read the service terms here. All downloadable files are also licensed under EdiFabric's license.

Disaster recovery

The InHouse API offers the option of operating fully in off-line mode, e.g. without calls to the Auth API, in the event that the Auth API is down for whatever reason.

We have procedures in place to send you instructions on how to configure the API to operate offline by manually installing the token and models into your environment until the Auth API is back up.

This procedure provides all standard models, however, if you use custom models, we recommend that you maintain a local backup of them, either as OpenAPI (in JSON or YAML format) or as DLL files.

EdiFabric

The product contains EdiFabric.dll which is an edition that can only be used with EdiFabric.Api.dll. You won't be able to use this edition of EdiFabric on its own or as a substitute for a product you previously obtained from edifabric.com.

EdiNation

The web EDI Translator is also included in the in-house edition. You will be able to execute all the operations such as validation of EDI files, translation between EDI and JSON, and generating EDI acknowledgments locally in the browser.

API calls quota and rate

All subscribers to EdiNation InHouse can still use the cloud EdiNation with the same API key as the Auth API with a limit of 10 operations per day.

When the quota is exceeded, the caller receives a 403 Forbidden response status code. When the call rate is exceeded, the caller receives a 429 Too Many Requests response status code.

Next steps

How to use Inhouse EDI API as Azure Function

How to use Inhouse EDI API as AWS Lambda

How to use Inhouse EDI API as ASP .NET Core