Welcome to Tillhubs Developer Guide. Jump right into the code, get a better understanding about the systems, or see the big picture. This guide is intended to get you up-and-running with real-world Tillhub applications.

You can find the top usecases of Tillhub's APIs on the left hand side sorted by language. We eat, speak, and breathe javascript, dart, and swift. Thus you will find mostly examples in those dialects and languages. If you fancy something else, we might be able to help. Just ask.

Node.js (JavaScript)

Tillhub's APIs are written in Node.js (opens new window) with express (opens new window) (and in some rare instances in golang (opens new window)), many of our frontends (such as the dashboard (opens new window)) in vuejs (opens new window). This is why we like to talk JavaScript so much.

Node.js is an asynchronous event-driven JavaScript runtime, for network applications such as RESTful APIs like ours. If you don't know Node.js (opens new window) yet, we recommend you to start here (opens new window).

Getting Started

To get started with the Tillhub API you will need to authenticated against it, either with API credentials provided by us, created in your account, or let your client/customer create it for you.

We will kick things off with the use of our API documentation and barebones Node.js/Javascript.

Dependencies

Node.js (opens new window)

Node package manager - NPM (opens new window)

axios js (opens new window)

Authentication

To verify your applications identity, you will need either the credentials to the account, and do a simple form of "implicit" auth to retrieve a JSON web token (opens new window), or make authorized calls by providing the beforementioned API Key. For more information check out the Tillhub API Docs (opens new window).

We need:

1. The tillhub resources such as: Auth Endpoint, clientAccountID (the UUID of the user account), and the credentials/api token
2. The development dependencies installed on our machine
3. A framework of our choice to call the endpoint (e.g.: axios js (opens new window))
4. A environment to execute (such as a server, our local dev machine, or a cloud function)

Caution: We discourage the storing, logging, or using of user credentials on server sided applications.

The API Endpoint can be taken from the Tillhub API Docs (opens new window)

https://api.tillhub.com/api/v0/users/login

Create a javascript file (depending on your env)

$ touch index.js

Init you project and follow the steps, for example like this

$ npm init

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (auth) auth-guide
version: (1.0.0) 0.0.1
description: Authentication on Tillhub
entry point: (index.js) 
test command: 
git repository: 
keywords: 
author: Tillhub
license: (ISC) MIT
About to write to /Users/myMachineXYZ/Documents/tillhub/guides/auth/package.json:

{
  "name": "auth-guide",
  "version": "0.0.1",
  "description": "Authentication on Tillhub",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Tillhub",
  "license": "MIT"
}


Is this OK? (yes) 

Feel free to skip a couple of options - we don't need tests, pre or post execution scripts etc. You will notice, that it created the package.json file with some meta information.

Install axios or any other http client package that handles requests for you, we will use axios for this example

$ npm install axios --save

Open your index.js in your preferred editor.

Require axios by adding

const axios = require('axios')

Follow the documentation of axios or your desired HTTP Client. With axios, in you index.js, you can now simply make a call to your desired url, and post the body there.

For the authentication endpoint, you will need to prepare a json body containing the users email and password. If you use the organisation login, please refer to the api documentation.

{
    "email": "your@email.com",
    "password": "yourhopefullysecurepassword123%%1"
}

In our case:

const authEndpoint = 'https://api.tillhub.com/api/v0/users/login'

axios.post(authEndpoint, body)
    .then( result => {
        console.log('Request successfully returned with: ', result.data.status)
        console.log(result.data)
    }).catch( err => {
        //console.log(err.response)
        console.log('Request failed with:', err.response.data.status)
        console.log('Error Message:', err.response.data.msg)
    }
)

Making a call for products

Now that you know how to make a post call to retrieve a valid session authorization token, you can start making calls to the products endpoint. Products can contain a lot of data, so be careful in the way you consume the API results.

In order to request data from the API, a authorization header must be set, containing the 'Bearer TOKEN'.

In this example, we have already retrieved a API token, usually you should get one that you can constantly use via the dashboard. The Tillhub account owner can issue API tokens for integrations, that can get used without time limit.

const clientId = 'UUIDofYourAccount'
const url = 'https://api.tillhub.com/api/v1/products/' + clientId
let bearer = null //Assign this value the value returned by the login call, or a given API Token

axios.get(url, { headers: {'Authorization': bearer}})
    .then( result => {
        console.log('status:', result.data.status)
        console.log('cursor:', result.data.cursor)
        console.log('which can be recursively called as long as it exists, to have a convenient option of fetching all the result objects.')
        console.log('count of objects:', result.data.count)
        console.log('first result:', result.data.results[0])
    }).catch( err => {
        //console.log(err.response)
        console.log('Request failed with:', err.response.data.status)
        console.log('Error Message:', err.response.data.msg)
    }
)

Schemas for validation

We are looking to extend this documentation for using tillhub schemas to validate and create sane datasets.