Difference between revisions of "The Telstar API"

From Telstar Wiki
Jump to navigation Jump to search
(Created page with " # 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 use...")
 
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
# TELSTAR Viewdata API (Under Development)


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


## 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 can be used to retrieve and update TELSTAR frames for the purpose of updating viewdata content and routing etc.
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).
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 a running server container (in this example called ''telstar-server'') using the following command


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.
    docker cp telstar-server:/opt/telstar/telstar-util-2.0.zip .


The utility *telstar-util* can be downloaded from here:
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.
[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).  
    xattr -d com.apple.quarantine telstar-util


The examples in this documentation demonstrate using *telstar-util*, *CURL* and Python 3.
The examples in this documentation demonstrate using the ''telstar-util'' command line utility.


__NOTE:__
'''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).
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
== 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.
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
     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.
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.
'''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
== 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.
The docker command used above included the *--init* parameter, this parameter creates a user based on the values specified in the following environment variables.
Line 43: Line 41:
     TELSTAR_API_PASSWORD
     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.
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.
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.
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
     telstar-util login localhost:8080 0 telstarapisecret


The *telstar-util* script is simply a wrapper to *CURL* and invokes the following command:
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.
 
    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.


## Retrievings Frames (GET)
## Retrievings Frames (GET)
Line 76: Line 55:
Once authorised, any frame can be retrieved with a simple GET request.
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*.
 
The frame will be returned and redirected to the file *500a.json*.  


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


### Using CURL
== Frames and JSON ==
 
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
 
### 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)
         
## Frames and JSON


The simplest frame that can be viewed on TELSTAR could be defined as follows.
The simplest frame that can be viewed on TELSTAR could be defined as follows.
Line 110: Line 70:
         "visible": true
         "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.
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 [http://edit.tf](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](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).
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](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](http://edit.tf). For more details of the frame structure and the various settings please see [Frames in Detail](frames.md).


Line 134: Line 106:
     }
     }


## Adding/Updating a Frame (PUT)
== 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.
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.
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  
     telstar-util addframe localhost:8080 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/frame"
== Deleting a 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/frame", headers=headers, data=payload, cookies=cookies)
 
## Deleting a Frame (DELETE)


A frame can be deleted using the HTTP DELETE method.
A frame can be deleted using the HTTP DELETE method.
### Using the Telstar Utility


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


     telstar-util deleteframe localhost:8080/frame/500a
     telstar-util deleteframe localhost:8080/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/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"
 
### Using Python
 
When using Python, the following code can be used.


    payload = json.dumps({"page_no": 500, "frame_id": "a"})
== Publish Changes ==
    headers = {
        'content-type': 'Content-Type: application/json'
    }
    response = requests.delete("localhost:8080/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.
As described previously, the API will perform its actions on the secondary database of a Telstar system.
Line 205: Line 129:


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.
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.
The following *telstar-utility* command will publish the frame 500a.
Line 212: Line 134:
     telstar-util publish localhost:8080/frame/500a
     telstar-util publish localhost:8080/frame/500a


### Using CURL
== Adding/Updating a User ==
 
The following *CURL* command will publish the frame 500a.
 
    curl -b cookies.txt "localhost:8080/publish/500a"
 
### Using Python


    To be added ...
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.
   
## 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.
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 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*.
The following *telstar-utility* command will create the user *800800* with the password *mysecretpassword*.
Line 234: Line 146:
     telstar-util adduser localhost:8080 800800 mysecretpassword
     telstar-util adduser localhost:8080 800800 mysecretpassword


### Using CURL
== Deleting a User ==


The following *CURL* command will create the user *800800* with the password *mysecretpassword*.
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.


    curl -X PUT -b cookies.txt -H "Content-Type: application/json" -d "{\"user_id\": 800800, \"password\": \"mysecretpassword\"}" "localhost:8080/user"
The following *telstar-utility* command will delete the user *800800*.


### Using Python
    telstar-util deleteuser localhost:8080 800800


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


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


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.
From a local machine execute the following command, changing the user and server to suit your own setup.


### Using the Telstar Utility
    ssh -L [LOCAL_IP:]LOCAL_PORT:DESTINATION:DESTINATION_PORT [USER@]SSH_SERVER


The following *telstar-utility* command will delete the user *800800*.
For example if the Telstar server was myserver.co.uk, you could use.


     telstar-util deleteuser localhost:8080 800800
     ssh -L 8002:myserver.co.uk:8001 john@myserver.co.uk
       
### Using CURL


The following *CURL* command will delete the user *800800*.
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.


    curl -X DELETE -b cookies.txt "localhost:8080/user/800800"
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.
 
### 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)

Latest revision as of 08:46, 16 April 2022

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

Retrieved from "https://wiki.glasstty.com/index.php?title=The_Telstar_API&oldid=322"