Application Structure

ShipEngine Connect applications are just NPM packages that meet the following requirements:

• Have a package.json file in the root directory, which specifies its name, version number, and dependencies.

• Have the @shipengine/connect-runtime package as a dependency in the package.json file.

• Have the appropriate app definition package as a dependency in the package.json file based on the type of app you're developing.

  • @shipengine/connect-carrier-api
  • @shipengine/connect-order-source-api

• Export an object with properties and methods that define the app's capabilities and functionality.

Other than that, everything else is up to you. We don't impose any specific folder structure or file naming convention. You can build your app just as you would build any other NPM package.

Getting Started

The ShipEngine Connect CLI makes it easy to get started with your app. It comes with built-in templates for each app type. Just run the connect init command, answer a few questions, and it'll create all the files and pre-populate much of the basic scaffolding for you.

For more details, see Creating Your First App.

Application Definition

The main export of your app's NPM package must be an object that defines your app's capabilities and functionality. The properties and methods of this object depend on the type of app you're building.

• Carrier app
• Order source app

Methods

As mentioned above, the main export of your application package must be an Application Definition object, which has properties and methods. The properties define your app's capabilities and features, but the methods provide your app's actual implementation. As you can imagine, the methods are probably where you'll spend most of your time when building an app.

Methods are just JavaScript functions that take input from ShipEngine Connect and return results to the platform. What happens in-between those two is entirely up to you. But, in general, most methods will consist of the following steps:

1) Transform the input data into whatever structure is needed by your API.

2) Call your API(s) to perform whatever operations are necessary and/or to retrieve whatever data was requested.

3) Transform the data from your API into the structure that's needed by ShipEngine Connect.

4) Return the data.

Forms

Forms are used gather data from an end-user that is interacting with your application from within one of our e-commerce applications. For example, you will need to supply a connection form that gathers login credentials from the end user so they can be authenticated with your API.

Definitions

In addition to the application definition, some application types include definition files for the services it provides. For example, each type of delivery service offered by a Carrier app will be described by a delivery service definition file.