The Telstar API

Introduction

Frames can be added to the system using either the Telstar API or by using a plug-in (see Implementing Response Frames)

The Telstar API, in conjunction with the cross platform Telstar Util software, provides a simple method of creating and managing pages. Data is passed to and from the API in JSON format, making the system very simple to use in any programming language.

The API is a restful API that uses the GET, PUT and DELETE HTTP methods. This makes it a simple process to add new frames and update existing frames. In order to use the system a username and password combination is used to create a security token. This token is then used for subsequent requests to access the API (see below).

Data is passed to and from the API in JSON format, making the system very simple to use in any programming language. The whole API could be used without any programming at all by using a command line utility such as CURL. To make things even simpler a *bash* utility called *telstar-util* is available that wraps *curl* making things even simpler.

The utility telstar-util can be downloaded from a running server container (in this example called telstar-server) using the following command

   docker cp telstar-server:/opt/telstar/telstar-util-2.0.zip .

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit). Note that the MacOS version may need to have the quarantine attribute reset. e.g.

   xattr -d com.apple.quarantine telstar-util

The examples in this documentation demonstrate using the telstar-util command line utility.

NOTE:

The API will perform its actions on the secondary database of a Telstar system. Once a page has been created, updated or deleted on the secondary database, the API can be used to publish the changes to the primary database if required (see Publish below).

Initialising the API

The Telstar API runs in a separate container. This uses the same base image but is started with a different parameter. e.g.

   docker run --rm -d --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID=2222222222 -e TELSTAR_API_PASSWORD=1234 -e TELSTAR_COOKIE_SECRET=b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar:amd64-2.0-RC3.4 api --port 8001 --init

This will start an api server listening on port 8001. the --init parameter will create the root user (user 0) based on the specified environment variables.

Remember to use a unique cookie secret for your system and keep it safe. The cookie secret is used to encrypt and decrypt the secure cookie within the telstar API. If this is made public, it may allow someone to create a valid authorisation cookie and impersonate a user of the system.

Authentication

The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.

   TELSTAR_API_USERID
   TELSTAR_API_PASSWORD

Typically this will be used to create the root user (user 0) and this is demonstrated in the docker-compose example (Orchestrating Telstar with Docker Compose) User 0 is a special user that has read, write and delete accesss to all pages within the system. Other users can be defined that have access to a specific group of pages.

All API users are common across primary and secondary databases. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. on both primary and secondary databases.

Once a User ID has been created it can be used to obtain a token. This token is then used in subsequent calls to the API. For example to access the API running on the local host, with the user ID specified above, the following telstar-util command could be used.

   telstar-util login localhost:8080 0 telstarapisecret

The important thing to note here is that cookies are saved to the file telstar-util.tok. This file contains the secure token. Subsequent requests to the API will forward the token in the request.

1. 1. Retrievings Frames (GET)

Once authorised, any frame can be retrieved with a simple GET request.

The frame will be returned and redirected to the file *500a.json*.

   telstar-util getframe localhost:8080 500a > 500a.json

Frames and JSON

The simplest frame that can be viewed on TELSTAR could be defined as follows.

   {
       "pid": {
           "page-no": 101,
           "frame-id": "a"
       },
       "visible": true
   }

This frame, is so basic that it doesn't even have content. The frame below includes some flashing content.

   {
     "pid": {
       "page-no": 101,
       "frame-id": "a"
     },
     "visible": true,
     "content": {
       "data": "[D]This is page[F]101a",
        "type": "markup"
     }
   }

Shown below is a more complete example of a JSON defined frame. With this particular frame, the actual viewdata content has been created using the editor at [1](http://edit.tf), this can be seen in the *content.data* and *content.type* keys. However, there are several ways to create frames other than using [2](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).

   {
     "pid": {
       "page-no": 0,
       "frame-id": "a"
     },
     "visible": true,
     "frame-type": "information",
     "content": {
       "data": "http://edit.tf/#0:QIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQMMKAbNw6dyCTuyZfCBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgKJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRAxQR4s6LSgzEEmdUi0otOogkzo0-lNg1JM-cCg8unNYgQIASBBj67OnXllWIMu7pl5dMOndty7uixBoy4dnTQsQIECBAgBIEHfLh2dNCDDuyINmnNl59POzKuQIECBAgQIECBAgQIECBAyQTotemggzoiCvFg1JEWkCnYemnfuw7EGHdkQIECBAgQIASBBp3dMvLdh6ad-7DsQbsvfmgw7siDvlw9NGXkuQIECBAgQM0EKrTkzotOmgkzo0-lNg1JM-cCh79vDDu8oMO7IgQIECAEgQYuvPTuy8-aDdl781wM6EjVKcVBMw9MvPogoctOPLzQIEDRBHn1otKdNizqiCTOjT6U2DUkz5wKlvw5OaxByw6dixAgBIEGHdkQUMPLZpw7cu7ouQIECBAgQIECBAgQIECBAgQIECBA2QR4NSLXg2UFOLSrSYcWmCnWKkWYsQVIsWNBsLEEOHMaIASBBh3ZEHTRlQQ9-zfz54diCHh7ZUGHJ2y7unXllXIECBAgQN0EifMkxINmmCqcsPbLsQYd2RBI37NOTD5QbsvfmuQIECBA4CHQc2TDpT50WogcMGCAScgoOnLTi69MqDpvQdNGnmgQIAaBBzy8u2nHlQd9PTQgqZdmXnvzdO-HllQYd2RBt38sq5AgQOQ0yfHQT40ZYgp2adSLNQSZ0aegTIKkWnUQUIMeLTQIECAokSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEiRIkSJEFeLBqSItJBGn0osODTqIBIM6EQIEFDDnyoFTJywvoECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECBAgQIECA",
       "type": "edit.tf"
     },
     "routing-table": [0,1,11,3,400,5,6,7,800,9,0],
     "cursor": false,
     "author-id": "editf-frame-generator",
     "navmsg-forecolour": "yellow",
     "navmsg-backcolour": "blue",
     "navmsg-highlight": "white"
   }

Adding/Updating a Frame

To add or update a frame the HTTP PUT request is used. If the frame already exists on TELSTAR the frame will be updated, if it does not exist then it will be created.

The following *telstar-utility* command will send the json frame stored in the file *500a.json* to the Telstar API using the Http PUT method.

   telstar-util addframe localhost:8080 500a.json

Deleting a Frame

A frame can be deleted using the HTTP DELETE method.

The following *telstar-utility* example will delete the frame 500a.

   telstar-util deleteframe localhost:8080/frame/500a

Publish Changes

As described previously, the API will perform its actions on the secondary database of a Telstar system.

Once a page has been created, updated or deleted on the secondary database, the API can be used to *publish* the changes to the primary database if required.

Publishing will update the primary database to that of the secondary for the specified frame. If the frame is deleted in the secondary and then published, it will be deleted in the primary also.

The following *telstar-utility* command will publish the frame 500a.

   telstar-util publish localhost:8080/frame/500a

Adding/Updating a User

Each user ID typically gives access to a single information provider page. In the case of major providers this could be one of the three digit page numbers and everything beneath it. For example the user ID 500, will have access to pages 500 including all decendants e.g. 5001-5009, 50011, 50021, 500111 etc. but not 501 or 502.

To add or update a user the HTTP PUT request is used. If the user already exists on TELSTAR the user will be updated, if it does not exist then it will be created.

The following examples add the user 800800 to the system. Note that only the *root* user (user 0) can make user changes. All passwords are stored in hashed form.

The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.

   telstar-util adduser localhost:8080 800800 mysecretpassword

Deleting a User

The following examples delete the user 800800 from the system using the HTTP DELETE method. Note that only the *root* user (user 0) can make user changes.

The following *telstar-utility* command will delete the user *800800*.

   telstar-util deleteuser localhost:8080 800800

Using an SSH Tunnel

The API could be kept private from the public and accessed using an SSH tunnel.

From a local machine execute the following command, changing the user and server to suit your own setup.

   ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER

For example if the Telstar server was myserver.co.uk, you could use.

   ssh -L 8002:myserver.co.uk:8001 john@myserver.co.uk

The above example creates an SSH connection to a server at myserver.co.uk using the username john. An SSH certificate is used to access the server so no password is needed. In the command the ports are mapped such that the local port 8002, is mapped to the remote port 8001.

The API is listening by default on port 8001 on the remote server. After executing the above command, the API can be accessed using the url http//localhost:8002 on the local machine.