Writing client programs

You can write a client program to talk to the Journyx API using any programming language that can make HTTP requests, which is virtually all of them.

On this page we provide simple examples in Python and JavaScript (Node.js).

In both cases, the examples show how to:

• Sign in to the Journyx API at the /api/v1/login endpoint.
• Use a session to store the wtsession cookie and send it with all subsequent requests.
• Send the required Accept, Origin, and X-Requested-With headers with all requests.
• Create a new Bill Type. See the Entry Codes API Reference for more information.
• Get the URL and ETag of the newly created Bill Type.
• Update the Bill Type using the ETag with the If-Match header.
• Delete the Bill Type.
• Sign out of the Journyx API at the /api/v1/logout endpoint.
• Check for errors after each request and raise an exception (or otherwise handle it) when an error occurs.

Python

#!/usr/bin/env python

"""
This script illustrates some basic usage of the Journyx API using Python. It
uses the `requests` library to make HTTP calls to the Journyx API, but you can
use any HTTP library you like.
"""

import requests


def main():
    # Change this to the base URL of your Journyx site
    base_url = "https://example.apps.journyx.com"

    # Use a session so that the wtsession cookie from the login is stored
    # and sent with all subsequent requests
    with requests.Session() as session:
        # All requests in this session should have these headers.
        # Important: Origin and X-Requested-With are required for the anti-CSRF security check
        session.headers.update(
            {
                "Accept": "application/json",
                "Origin": base_url,
                "X-Requested-With": "XMLHttpRequest",
            }
        )

        # Sign in to the Journyx API
        sign_in_url = f"{base_url}/api/v1/login"

        # You can use an API Key in the password field
        sign_in_data = {"username": "admin", "password": "YOUR_PASSWORD_HERE"}

        response = session.post(sign_in_url, json=sign_in_data)
        # Check for errors (raises an exception if the response is an error)
        response.raise_for_status()

        # Create a new Bill Type
        create_bill_type_url = f"{base_url}/api/v1/entry_codes/codes_bill_types"
        create_bill_type_data = {
            "pname": "API Test 1",
            "description": "Description of API Test 1",
            "status": "Loggable and Reportable",
            "autoadd": False,
        }
        response = session.post(create_bill_type_url, json=create_bill_type_data)
        response.raise_for_status()

        # Get the ID and ETag of the newly created Bill Type
        # The ETag is needed for updating the Bill Type.
        bill_type_url_rel = response.headers["Location"]
        bill_type_url = f"{base_url}{bill_type_url_rel}"
        print(f"Created Bill Type ID: {bill_type_url}")

        response = session.get(bill_type_url)
        response.raise_for_status()

        bill_type_data = response.json()["results"].copy()
        bill_type_data["description"] = "Updated description of API Test 1"
        bill_type_etag = response.headers["ETag"]

        # Update the Bill Type - important: the If-Match header is required
        response = session.put(
            bill_type_url, json=bill_type_data, headers={"If-Match": bill_type_etag}
        )
        response.raise_for_status()

        # Re-fetch the Bill Type to verify that it was updated
        response = session.get(bill_type_url)
        response.raise_for_status()
        assert (
            response.json()["results"]["description"]
            == "Updated description of API Test 1"
        )
        print(f"Bill Type updated successfully: {bill_type_url}")

        # Delete the Bill Type
        response = session.delete(bill_type_url)
        response.raise_for_status()
        print("Bill Type deleted successfully.")

        # End the session (logout)
        sign_out_url = f"{base_url}/api/v1/logout"
        response = session.post(sign_out_url)
        response.raise_for_status()

    return


if __name__ == "__main__":
    main()

JavaScript

/**
 * This script illustrates some basic usage of the Journyx API using Node.js
 * and the `got` and `tough-cookie` libraries.
 */

import got from "got"

import {CookieJar} from "tough-cookie"

async function main() {
  // Change this to the base URL of your Journyx site
  const baseUrl = "https://example.apps.journyx.com"

  // Use a cookie jar to store cookies (like the wtsession cookie from login)
  const cookieJar = new CookieJar()

  // Create a got instance with default settings
  const client = got.extend({
    headers: {
      Accept: "application/json",
      Origin: baseUrl,
      "X-Requested-With": "XMLHttpRequest",
    },
    cookieJar: cookieJar,
    responseType: "json",
    throwHttpErrors: true,
  })

  try {
    // Sign in to the Journyx API
    // You can use an API Key in the password field
    const signInData = {username: "admin", password: "YOUR_PASSWORD_HERE"}
    const signInResponse = await client.post(`${baseUrl}/api/v1/login`, {
      json: signInData,
    })

    // Create a new Bill Type
    const createBillTypeData = {
      pname: "API Test 1",
      description: "Description of API Test 1",
      status: "Loggable and Reportable",
      autoadd: false,
    }

    const createBillTypeResponse = await client.post(
      `${baseUrl}/api/v1/entry_codes/codes_bill_types`,
      {
        json: createBillTypeData,
      },
    )

    // Get the URL of the newly created Bill Type
    const billTypeUrlRel = createBillTypeResponse.headers["location"]
    const billTypeUrl = `${baseUrl}${billTypeUrlRel}`
    console.log(`Created Bill Type ID: ${billTypeUrl}`)

    // Fetch the Bill Type
    const getBillTypeResponse = await client.get(billTypeUrl)
    console.log("Got Bill Type:", getBillTypeResponse.body.results)

    const billTypeData = {...getBillTypeResponse.body.results}
    billTypeData.description = "Updated description of API Test 1"
    const billTypeEtag = getBillTypeResponse.headers["etag"]

    // Update the Bill Type
    await client.put(billTypeUrl, {
      json: billTypeData,
      headers: {
        "If-Match": billTypeEtag,
      },
    })

    // Re-fetch the Bill Type to verify that it was updated
    const verifyBillTypeResponse = await client.get(billTypeUrl)
    if (
      verifyBillTypeResponse.body.results.description ===
      "Updated description of API Test 1"
    ) {
      console.log(`Bill Type updated successfully: ${billTypeUrl}`)
    } else {
      console.error("Bill Type update failed.")
    }

    // Delete the Bill Type
    await client.delete(billTypeUrl)

    // End the session (logout)
    await client.post(`${baseUrl}/api/v1/logout`)
  } catch (error) {
    console.error("Error:", error)
  }
}

main()