Elliott API (JSON Web Service)


Prerequisites:

Features that require PSQL v13 or later

Pagination


Elliott API supports paging. In some API routes such as the /order/search, the API could return potentially large result set. To enhance performance, you can specify a combination of PageNumber and PageSize in the request to page through the result.  The new pagination feature relies on the new LIMIT and OFFSET sql syntax that only become available with the PSQL v13 release. If you are running PSQL server version < 13, you will get an error if you attempt to use the paging feature. 

Example: 
If there are 1000 items in the results, to get the 101-200 items you can specify PageNumber=2, PageSize = 100.

Note:
If you are running PSQL v12, you can still limit the result set by specifying PageNumber = 1 and PageSize = N to retrieve the first N items. In this special case, the the API will use the TOP command instead.

From ElliottApi documentation (included in swagger):
PageNumberinteger($int32)
Specify page number. Default is 1. PageNumber starts at 1.
PageSizeinteger($int32)
Specify page size. Default is 100.

From PSQL v13 release notes, the LIMIT and OFFSET syntax only become available with the v13 release:
  PSQL v13 extends its support for SQL with the following new features:
 As an alternative to TOP, LIMIT… OFFSET… syntax is now supported to extract a set of rows from
a query result  

SOAP to JSON Equivalents

Service

SOAP Method

Option

JSON Route

Changes

CustomerInquiry

Customer Resource

GetCustomerInfo

/Customer/get

GetARCodes

GetARSLMFIL

/ElliottQuery/executeQuery

GetARCUSTYP

/ElliottQuery/executeQuery

GetSTATEFIL

/ElliottQuery/executeQuery

GetSHIPVIA

/Customer/shipViaCodes/get

GetTerms

/Customer/termsCodes/get

GetTax

/Customer/taxCodes/get

SearchCustomer

/Customer/search

Order by restricted to CUS_NO and CUS_SEARCH_NAME.  Numeric search fields that supported operators such as > or < should be processed using the AdditionalWhere parameter. The DetailLevel parameter is now supported through the ResultColumns parameter.

FFLNearYou

FFLNearYou Resource

Find FFL

/FFLNearYou/get

Byte stream array of link images not supported at this time.

InvoiceInquiry

Invoice Resource

GetInvHdrByCusNo

/Invoice/search

Order by restricted to INV_NO, INV_CUSTOMER_NO,  INV_ORDER_NO, INV_DATE.

GetOneInvoiceDetail

/Invoice/get

ItemInquiry

GetIMCodes

Item Resource

GetProductCategories

/Item/productCategories/get

GetUserDefinedCodes

/ElliottQuery/executeQuery

GetMatCstTypes

/ElliottQuery/executeQuery

GetBuyerCodes

/Item/buyerCodes/get

GetDistinctValues

Not Supported

SearchItem

/Item/search

Order by restricted to ITEM_NO and ITEM_DESC_SEARCH. The DetailLevel parameter is now supported through the ResultColumns parameter. The customerNo parameter is not supported at this time.

SearchItemMultipleLocation

/Item/search

Quantities from multiple locations not supported at this time.

GetItemAttrib

/Item/attributes/get

GetItemNote

/Item/notes/get

GetItemSetup

/ElliottQuery/executeQuery

GetAllMatCstType

/ElliottQuery/executeQuery

GetAllPrdCat

/Item/productCategories/get

GetOnePrdCat

/ElliottQuery/executeQuery

GetAllBuyerCode

/Item/buyerCodes/get

GetItemDistinctValue

Not Supported

GetOneItemDetail

/Item/get

customerNo

Not supported at this time

attribWebFlag

/Item/attributes/get

noteWebFlag

/Item/notes/get

imageLinkType

/Item/links/get

Byte stream array of link images not supported at this time.

additionalLinkType

/Item/links/get

Not supported at this time

GetFeatureOption

/Item/featureOption/get

GetInvoiceHistory

/Item/searchItemInvoice

Order by option not supported at this time.

OrderInquiry

Order Resource

GetOrder

/Order/search

Order by restricted to ORDER_NO and ORDER_CUSTOMER_NO

GetOneOrderDetail

/Order/get

ResellerFinder

ResellerFinder Resource

FindReseller

/ResellerFinder/get

Order by option not supported at this time.

Vendor

Vendor Resource

GetAllVendor

/Vendor/search

Order by restricted to VEND_NO and VEND_SEARCH_NAME

Logging Configuration

Elliott API uses aspnetcore + nlog for logging. The configuration can be configured with the nlog.config. There are two main sections targets and rules. 

Targets 

Targets specify the destination log entries will be written to.

Exampe - the following entry is the default target for database trace.

    <target name="databaestracefile" xsi:type="AsyncWrapper" queueLimit="5000" overflowAction="Discard">
      <target
        xsi:type="File"
        layout="${longdate} ${message}"
        fileName="logs/database/database.txt"
        archiveFileName="logs/database/database.{#####}.txt"
        archiveAboveSize="10240000"
        archiveNumbering="Sequence"
        maxArchiveFiles="10"
        concurrentWrites="true"
        keepFileOpen="false" />
    </target>

  • type - specify the type of the target, in this example, log entries will be written to a file. You can also specify other targets such as email or to network. For more information, you can look up nlog documentation.
  • fileName -  specify the file to write log entries to. You can use absolute path, or relative path. Relative path is relative to the path of the Elliott API root folder
  • archiveFileName - specify the fileName to use when the log file is archived
  • archiveAboveSize - specify the size the log file will be archived
  • archiveNumbering - specify how archive file will be named.
  • maxArchiveFiles - specify the number of archive files to keep. 

Rules

Rules specify the what will be logged, and where it will be logged.

Example:- following entry will log all log entries output by any classes in "ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware" to the apitracetarget. 

 <logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.*" level="Trace" writeTo="apitracefile" final="true" />  

  • enabled - specify whether this rule is enabled
  • name - specify the logger name. The logger names are usually the fully qualified namespace + class name in the Elliott API. You can append the "*" wildcard character at the end of a namespace to include all logger in a related namespace.
  • level - specify the level of logging that will be included
  • writeTo - the target to write to
  • final - if true, it will stop matching on further rule

Common Configuration 

Elliott API is distributed with a set of common rules that provide extensive logging that's intended to provide detail logging when it's first setup. Prior to going to production, you may choose to adjust the loggers to only log errors and re-enable detail logging when you need to troubleshoot problems. The following are the default loggers, at the minimum, you will want to enable the logger than writes to "errorfile" (bolded in the example below).

    <logger enabled="true" name="ElliottApi.Infrastructure.Data.*" level="Trace" writeTo="databaestracefile" final="true" />
    <logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.*" level="Trace" writeTo="apitracefile" final="true" />
    <logger enabled="true" name="ElliottApi.Infrastructure.Providers.Nmi.*" level="Trace" writeTo="nmitracefile" final="true" />
    <logger enabled="true" name="*" minlevel="Error" writeTo="errorfile" />
    <logger enabled="true" name="*" minlevel="Trace" writeTo="logfile" />  

API Logging Configuration

The default rule logs all API raw requests responses to the apitracefile target. 

<logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.*" level="Trace" writeTo="apitracefile" final="true" />  

The "name" follows this pattern " ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.{route-where-slash-is-replaced-by-dash}". You can use it to target a specific API. For example, if you are only interested in the log messages for "order/search" route. You can have the following rule entry:

  <logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.order-search*" level="Trace" writeTo="apitracefile" final="true" />    

You can also target multiple routes by having multiple entries that target different routes. For example, to target "order/search" and "vendor/search" routes:

  <logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.order-search*" level="Trace" writeTo="apitracefile" final="true" />     

  <logger enabled="true" name="ElliottApi.Infrastructure.Owin.ApiLoggingMiddleware.vendor-search*" level="Trace" writeTo="apitracefile" final="true" />     


Troubleshooting: 

If you get System.MissingMethodException after you install the ElliottApi, please check and make sure .NET 4.61 is installed on the hosting machine.
Application: ElliottApi.Web.exe
Framework Version: v4.0.30319
Description: The process was terminated due to an unhandled exception.
Exception Info: System.MissingMethodException
Stack:
  at Microsoft.AspNetCore.Hosting.WebHostBuilder.Build()
  at ElliottApi.Web.Program.Main(System.String[])

If you receive an error stating "[Exception]:[Character literal must contain exactly one" after providing a where condition for a string/character field in an AdditionalWhere parameter, this can be addressed by using single quotes around the condition and double quotes around the value. For example, the following AdditionalWhere parameter used in the /Vendor/search method will generate an error.

{
  "AdditionalWhere": "VEND_ST = 'OH'",
  "PageNumber": 1,
  "PageSize": 10
}

If it is revised to the following statement, the error is resolved.

{
  "AdditionalWhere": 'VEND_ST = "OH"',
  "PageNumber": 1,
  "PageSize": 10
}

VYC, CLS
Created 2019-08-21
Updated 2019-09-10

Feedback and Knowledge Base