The Telstar API

1. TELSTAR Viewdata API (Under Development)

__*** Please note TELSTAR as an application is still under development and subject to change. ***__

1. 1. Introduction

The TELSTAR API can be used to retrieve and update TELSTAR frames for the purpose of updating viewdata content and routing etc.

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).

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.

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 here: [https://bitbucket.org/johnnewcombe/telstar-server/downloads/(https://bitbucket.org/johnnewcombe/telstar-server/downloads)

Versions exist for Linux and MacOS (amd64 and arm64), and Windows (32 and 64 bit).

The examples in this documentation demonstrate using *telstar-util*, *CURL* and Python 3.

__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).

1. 1. 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 --name telstar-api --network telstar-network -p 8001:8001 -e TELSTAR_API_USERID 0 -e TELSTAR_API_PASSWORD telstarapisecret -e TELSTAR_COOKIE_SECRET b6c7a826-96d6-4f45-88c4-3cf27cc2c647 johnnewcombe/telstar 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.

1. 1. 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 and this is demonstrated in the docker-compose example (see [Using Docker Compose](docker_compose.md)) 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 *telstar-util* script is simply a wrapper to *CURL* and invokes the following command:

   curl -X PUT -c cookies.txt -H "Content-Type: application/json" -d "{\"un\": 0, \"telstarapisecret\": \"$PW\"}" "localhost/login"

The important thing to note here is that cookies are saved to the file *cookies.txt*. The cookie file contains the secure cookie containing the token. Subsequent requests to the API must forward the cookies in the request see GET and PUT methods below.

In Python, the same can be achieved using the requests package e.g.

   payload = json.dumps({"un": 0, "pw": "telstarapisecret"})
   headers = {
       'content-type': 'Content-Type: application/json'
   }
   response = requests.put("localhost:8080/login", headers=headers, data=payload)
   cookies = response.cookies
   print(response.text)

In this case the cookies are retrieved and stored in a variable. This variable should be passed in subsequent calls to the API.

The cookie is valid for 24 hours and should be passed in each call to the API.

1. 1. Retrievings Frames (GET)

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

1. 1. 1. Using the Telstar Utility

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

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

1. 1. 1. Using CURL

Note that in the example below that the *cookies.txt* file is sent with the request, see Authentication above.

   curl -b cookies.txt "localhost:8080/frame/500a"

If required, the returned json data can be redirected to a file for example.

   curl -b cookies.txt "localhost:8080/frame/500a" > 500a.json

1. 1. 1. Using Python

When using Python, the same can be achieved using the requests package e.g.

   response = requests.get("lpcalhost:8080/frame/500a", cookies=cookies)
   data = json.loads(response.text)
         

1. 1. 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. However, when viewed within TELSTAR it will show a default welcome message.
    

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"
   }

1. 1. Adding/Updating a Frame (PUT)

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.

1. 1. 1. Using the Telstar Utility

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 
   

1. 1. 1. Using CURL

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

   curl -X PUT -b cookies.txt -H "Content-Type: application/json" -d @500a.json "localhost:8080/frame"

1. 1. 1. Using Python

When using Python, there are several ways to post the json data. The first involves opening the file and reading in the data before using the POST method, this sends the data in much the same way as a web form would.

It is important to note that the field name must be *data* as in the following example.

   payload = <some json frmae object>
   headers = {
       'content-type': 'Content-Type: application/json'
   }
   response = requests.put("localhost:8080/frame", headers=headers, data=payload, cookies=cookies)

1. 1. Deleting a Frame (DELETE)

A frame can be deleted using the HTTP DELETE method.

1. 1. 1. Using the Telstar Utility

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

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

1. 1. 1. Using CURL

The following *CURL* examples will delete the frame 500a. All three examples use the HTTP PUT method and work the same way. Simply choose the most appropriate for you particular application.

This example appends the page id (page number + frame id) to the url.

   curl -X DELETE -b cookies.txt localhost:8080/frame/500a

This example sends the page id (page number + frame id) encoded as JSON data in the request body.

   curl -X DELETE -b cookies.txt -H "Content-Type: application/json" -d "{\"page_id\": \"500a\"}" "localhost:8080/frame"

This example sends the page number and frame id encoded as JSON data in the request body.

   curl -X DELETE -b cookies.txt -H "Content-Type: application/json" -d "{\"page_no\": 500, \"frame_id\": \"a\"}" "localhost:8080/frame"

1. 1. 1. Using Python

When using Python, the following code can be used.

   payload = json.dumps({"page_no": 500, "frame_id": "a"})
   headers = {
       'content-type': 'Content-Type: application/json'
   }
   response = requests.delete("localhost:8080/frame", headers=headers, data=payload, cookies=cookies)
   

1. 1. 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.

1. 1. 1. Using the Telstar Utility

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

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

1. 1. 1. Using CURL

The following *CURL* command will publish the frame 500a.

   curl -b cookies.txt "localhost:8080/publish/500a"

1. 1. 1. Using Python

   To be added ...
   

1. 1. Adding/Updating a User

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.

1. 1. 1. Using the Telstar Utility

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

   telstar-util adduser localhost:8080 800800 mysecretpassword

1. 1. 1. Using CURL

The following *CURL* command will create the user *800800* with the password *mysecretpassword*.

   curl -X PUT -b cookies.txt -H "Content-Type: application/json" -d "{\"user_id\": 800800, \"password\": \"mysecretpassword\"}" "localhost:8080/user"

1. 1. 1. Using Python

   payload = json.dumps({"user_id": 800800, "password": "telstarapisecret"})
   headers = {
       'content-type': 'Content-Type: application/json'
   }
   response = requests.put("localhost:8080/user", headers=headers, data=payload, cookies=cookies)

1. 1. 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.

1. 1. 1. Using the Telstar Utility

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

   telstar-util deleteuser localhost:8080 800800
       

1. 1. 1. Using CURL

The following *CURL* command will delete the user *800800*.

   curl -X DELETE -b cookies.txt "localhost:8080/user/800800"

1. 1. 1. Using Python

   payload = json.dumps({"user_id": 800800})
   headers = {
       'content-type': 'Content-Type: application/json'
   }
   response = requests.delete("localhost:8080/user", headers=headers, data=payload, cookies=cookies)