Skip to content
This repository has been archived by the owner on May 11, 2020. It is now read-only.

Latest commit

 

History

History
156 lines (101 loc) · 4.67 KB

README.md

File metadata and controls

156 lines (101 loc) · 4.67 KB
Raw

ShipCloud API Binding for JavaScript

This project provides a complete mapping of ShipCloud's API. At advarics we're currently evaluating their services and because our applications rely heavily on web technologies we've decided to create a proper JS API-binding. As far as we know there aren't any similar projects available.

For a C++ version visit this repo.

Structure

We use these fine open source packages and languages:

Api Access Keys

However, to be able to communicate with the API you'll have to register first to obtain the free developer access keys. Then open src/config.json and put your keys in there.

shipcloud_keys

Api Structure

The structure under src/api/v1 strictly follows the original documentation. It comprises of these sub-directories:

calls
config
public
types

Calls directory

This directory contains all available API calls:

For example, the Address-Call comprises of three calls according to the docs: create, index and read

Therefore we define these call-mappings in our Address class: read, readAll and create. In general these classes define the high-level portion of the complete API-binding as these don't touch more specific aspects like JSON or HTTP-Requests.

Config directory

This directory contains elements which aren't described in the original docs.

Api Auth

Api-Auth class contains some helper methods for auth-key management.

Public directory

ShipCloud

This directory contains the public ShipCloud interface. Clients should use it for type-safe API access.

Types directory

This directory contains all message and response definitions.

Additional Services
Address 
Package 
Pickup 
Rate 
Responses ---
             |
             | ---> Address-Response, 
             | ---> Carrier-Response
             | ---> Pickup-Response 
             | ----> etc.
Shipment 
Shipment Quote 
Tracker 
Webhook

These classes are DTOs for easy transfer between client and server.

REST & JSON

All API calls go via the RequestHelper class. This class utilizes node-fetch and implements the GET, POST, PUT and DELETE requests.

Building

First, install node packages with npm install.

Development bundle

To create a development bundle type:

npm run build:dev

Production bundle

To create a production bundle type:

npm run build:prod

After a successful build a new bundle will be created in dist.

Hot-Module reloading with WebPack

To activate hot-module reloading during the development type:

npm run start:hmr

Usage

Console Client

To test the binding in Node type:

npm run start:client

Now a special node instance called ts-node will load index.ts to boot the API client.

Browser Client

Type:

npm run build:client

The generated build will be located in dist/client.

Copy this directory to your web server and open index.html.

Notice: It depends on your current setup what and if any data will be sent back from ShipCloud. Also, don't forget to check your API key in src/config.json if you experience any problems.

License

MIT