Wiki

Clone wiki

telstar-server / telstar_api

TELSTAR Viewdata API (Under Development)

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

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/telstar-util

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

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.

Authentication

The docker command used above included the --init parameter, this parameter creates the user root user (user id 0) based on the values specified in the specified environment variables. This is also demonstrated in the docker-compose example (see Using 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/telstar 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/telstar/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.

Retrievings Frames (GET)

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

Using the Telstar Utility

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

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

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/telstar/frame/500a"

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

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

Using Python

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

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

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 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 http://edit.tf. For more details of the frame structure and the various settings please see Frames in Detail.

{
  "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 (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.

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/telstar 500a.json

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/telstar/frame"

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/telstar/frame", headers=headers, data=payload, cookies=cookies)

Deleting a Frame (DELETE)

A frame can be deleted using the HTTP DELETE method.

Using the Telstar Utility

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

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

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/telstar/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\"}" "$URL/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/telstar/frame"

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/telstar/frame", headers=headers, data=payload, cookies=cookies)

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.

Using the Telstar Utility

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

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

Using CURL

The following CURL command will publish the frame 500a.

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

Using Python

To be added ...

Adding/Updating a User

To add or update a user 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 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.

Using the Telstar Utility

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

telstar-util adduser localhost:8080/telstar 800800 mysecretpassword

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/telstar/user"

Using Python

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

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.

Using the Telstar Utility

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

telstar-util deleteuser localhost:8080/telstar 800800

Using CURL

The following CURL command will delete the user 800800.

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

Using Python

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

Updated