Getting Started

• 1: Postman Collections
• 2: Session Management and Configuration
• 3: Searching, Paging and ExtendedInfo
• 4: Common Errors

1 - Postman Collections

Collection Files

We continually update our collection files to reflect the changes and updates we make to the xAPI.

2 - Session Management and Configuration

Session Management

The External API (XAPI) uses a token-based access model in order to authorize access to its endpoints. Understanding the security and session management architecture ensures that the least disruptions occur while using the XAPI.

Users, Tokens, and Sessions

The three main components of the XAPI security framework are:

1. EPASS Users
2. Web Tokens
3. Web Sessions

EPASS Users

The user name and password to be used to login to the XAPI are maintained within EPASS. The users are maintained in the same area as all of the standard EPASS users except that they must be of type: “API User”. This “API User” type is permitted access to the XAPI; however, it cannot be used to login to the EPASS Windows application.

EPASS XAPI accounts are configured in the standard admin area of EPASS:


JSON Web Tokens

The XAPI uses JSON Web Tokens (JWT) to permit access to its web methods. In summary, an application logs into the XAPI using the EPASS user and password and then receives a JWT token. Subsequent calls to the XAPI require the calling application to pass the JWT token in the BEARER authorization header.

The session process involves two tokens: the session token (referred to just as the token), and the refresh token. As far as the application is concerned the session token is the only token; however, in the case that the token expires the application can quickly re-establish itself with a new session token without having to resent the user/password credentials.

More about JWT Tokens

More about Refresh Tokens

Below is a drawing showing the processes involved with managing the token states.


Web Sessions

An XAPI session is simply a high-level abstraction of the XAPISession table, session token, and refresh tokens. Each session has a corresponding row in the XAPISession table of which there are some details about the session. At any given point, deleting a record in the XAPISession table will result in the immediate invalidation of the session and all access will be revoked, including the ability to use the refresh token.

Configuration

The EPASS External API (XAPI) is configured through a single JSON config file: “appsettings.json”. This file is located in the root of the installation folder and contains a variety of important settings.

appsettings.json

{
  ...
  "XAPI": {
    "LogEnabled": true,
    "LogInfo": true,
    "LogErrors": true,
    "LogDebug": true,
    "LogFileLocation": "",
    "TokenExpiryInMinutes": 1440,
    "RefreshExpiryInMinutes": 1440,
    "TrackStatistics": true,
    "TrackStatisticsSize": 500,
    "TrackStatisticRequest": true,
    "TrackStatisticResponse": true,
    "CachedLookupsThreshold": {
      "base": 1000,
      "varAR": 1000,
      "Branch": 1000,
      "Misc": 1000,
      "ModelEcoFee": 1000
    },
    "CachedLookupsTimeInSeconds": 3600
  },
  "Licensing": { ignore },
  "ConnectionStrings": {
    "DBName": "Server=<IP>;Port=<port>;User=<dbuser>;Password=<dbpassword>;Namespace=<dbname>;Max Pool Size = 5;Min Pool Size = 1;"
  }
}

xAPI Object

Logging

Token/Session

Statistics

The statistics feature allows the recording of requests and responses which provides programmers with the ability to view the raw request data that was received by an endpoint and the raw response data sent back to the caller. The ‘track statistics’ feature is not intended for production usage but rather for debugging a particular issue.

Cached LookUps

To reduce stress on the database and increase access speed, the system can locally cache the data for commonly used tables containing data that doesn’t change very often. You can designate which data tables should get cached by including their name in appsettings.json. The tables that support caching are mostly found in EPASS under System Maintenance > Tables.

ConnectionStrings Object

The ConnectionStrings sections may have an unlimited number of databases configured. During the login process, the calling application supplies a user, password, and organization id (known as the database name). Each database name must be unique. The following is a sample database string for a database called “DEMO”:

"DEMO": "Server=127.0.0.1;Port=12345;User=User1;Password=abcdef;Namespace=DEMO;Max Pool Size = 5;Min Pool Size = 1;"

Server: IP address to DNS Name of the database server.

Port: Port number permitted for connections to the database server.

User: This is a database user and not an EPASS user.

Password: The password field is unique; it allows a person to type in a plain text password such as “MyPassword123” and once the application starts it will encrypt the password and write the cipher text back into this connection string.

Max Pool Size: This will throttle the maximum number of database connections permitted by the XAPI application. If this number is reached, subsequent requests will be delayed while waiting for a free connection.

Min Pool Size: This is the initial size of the application pool. This will only make a difference in situations where the application is requiring quick responsiveness after an application restart.

3 - Searching, Paging and ExtendedInfo

Building a Search Query

Most EPASS records can be retrieved using a SEARCH endpoint and sending a query in the payload.

For example, to search for and retrieve a customer record by it’s ID (or code), you would send:

POST /customer/search
{
    "query": {
        "fieldName": "ID",
        "eval": "EQUAL",
        "value": "12345"
    }
}

You can expand the search query by including a number of sub-query arrays.

To retrieve a customer record where the customer’s last name equals “Smith”, and they are located in the city of Vancouver, you would send:

POST /customer/search
{
    "query": {
        "fieldName": "lastname",
        "eval": "EQUAL",
        "value": "SMITH"
    }, 
    "subquery":[
        {
            "logic": "AND",
            "query": {
                "fieldName": "CITY",
                "eval": "EQUAL",
                "value": "Vancouver"
            }
        }
        
    ]
}

Search queries can be as expansive as needed by adding additional sub-queries and changing the logic operator.

In this example, all customer records with the last name “Smith” or “Jones” that live in Vancouver are retrieved:

POST /customer/search
{
    "query": {
        "fieldName": "lastname",
        "eval": "EQUAL",
        "value": "SMITH"
    }, 
    "subquery":[
        {
            "logic": "OR",
            "query": {
                "fieldName": "lastname",
                "eval": "EQUAL",
                "value": "JONES"
            }
        },
        {
            "logic": "AND",
            "query": {
                "fieldName": "city",
                "eval":"EQUAL",
                "value": "Vancouver"
            }
        }
    ]
}

Paging

Paging is a core component of endpoint searching provided by the xAPI. Paging prevents overconsumption of resources for a single query, and allows the calling application to control their response speed to payload size ratio.

Each time a search is executed it returns an indicator which informs the calling application whether or not there are more records after this page.

For example, if the search returned 1,000 rows and the page size was set to 100, the calling application would need to call the endpoint 10 times to return all 1,000 rows of data.

Here’s an example of a search endpoint with paging:

POST /customer/search
{
   "paging": {
        "pageSize": 100,
        "pageStartId": 0
    },
    "query": {
        "fieldName": "lastname",
        "eval": "EQUAL",
        "value": "SMITH"
    }  
}

The results of this query will return the highest unique record key on this given page, as well as provide a Boolean value indicating if there are more pages.

{
  "Results": {
    "Success": true,
    "Message": "Returned 100 records",
    "LastException": null
  },
  "Paging": {
    "PageSize": 100,
    "LargestID": 271620,
    "PagesRemaining": true
  }
    ...

In the above example, the next query would simply issue the request again except change the starting page ID:

POST /customer/search
{
   "paging": {
        "pageSize": 100,
        "pageStartId": 271620
    },
    "query": {
        "fieldName": "lastname",
        "eval": "EQUAL",
        "value": "SMITH"
    }  
}

ExtendedInfo

To include fields from related tables in your search query, you have to include them in an ExtendedInfo object. The ExtendedInfo object is added to the end of your search query.

For example, to return the details of an invoice, including the details of the primary Salesperson that’s attached to the invoice (which is contained in the Salesperson table), you would send the following endpoint and query:

POST /invoicing/invoice/search/code
{
    "query": {
        "invoicecode": "123456" 
    },
    "extendedInfo": {
        "Salesperson1": []
    }
}

The response would include data from all the invoice fields, as well as the data from the Salesperson table. This data is included at the end of the response, within an ExtendedInfo object:

...
"ExtendedInfo": {
        "Salesperson1": {
          "Fields": {
            "ID": 345,
            "Code": "00001",
            "Description": "ASH WILLIAMS",
            "SalesGroup": "INSIDE SALES",
            "Obsolete": false,
            "BranchCode": "Default",
            "Email": "awilliams@acme.com",
            "CurrentSales": false
          }
        }
      }

You can also specify which data fields are returned by entering the field names in the table array. Using the above example, if you wanted the query to return just the Salesperson’s ID and Description, you would send the following endpoint:

POST /invoicing/invoice/search/code
{
    "query": {
        "invoicecode": "123456" 
    },
    "extendedInfo": {
        "Salesperson1": [
            "ID",
            "DESCRIPTION"
        ]
    }
}

The response will include the data from the ID and Description fields only:

...
"ExtendedInfo": {
        "Salesperson1": {
          "Fields": {
            "ID": 345,
            "Description": "ASH WILLIAMS"
          }
        }
      }

4 - Common Errors

The xAPI uses common HTTP response codes to indicate successful or unsuccessful request attempts. Generally, any 2XX response codes indicate a successful request, while errors are indicated with a 4XX code. In most cases, error messages are supplied that explain why the request failed.

The following are common errors you may receive when sending requests to the xAPI.