The Telstar API - Revision history

John: /* Creating the SSH Tunnel */

2022-04-16T08:46:52Z

Creating the SSH Tunnel

← Older revision		Revision as of 08:46, 16 April 2022
Line 154:		Line 154:
	telstar-util deleteuser localhost:8080 800800		telstar-util deleteuser localhost:8080 800800

	== ~~Creating the~~ SSH Tunnel ==		== Using an SSH Tunnel ==

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

John at 08:46, 16 April 2022

2022-04-16T08:46:32Z

← Older revision		Revision as of 08:46, 16 April 2022
Line 153:		Line 153:

	telstar-util deleteuser localhost:8080 800800		telstar-util deleteuser localhost:8080 800800

			== Creating the 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.

John: /* Introduction */

2022-04-15T05:35:38Z

Introduction

← Older revision		Revision as of 05:35, 15 April 2022
Line 10:		Line 10:
	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.		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-03:telstar-util-2.0.zip .~~
	The utility ''telstar-util'' can be downloaded from a running server container (in this example called ''telstar-server'') using the following command		The utility ''telstar-util'' can be downloaded from a running server container (in this example called ''telstar-server'') using the following command

John: /* Introduction */

2022-04-15T05:35:18Z

Introduction

← Older revision		Revision as of 05:35, 15 April 2022
Line 10:		Line 10:
	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.		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~~://~~glasstty.com/wp-content/uploads/2022/04~~/telstar-util-2.0.zip).
			docker cp telstar-server-03:telstar-util-2.0.zip .
			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.		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.

John: /* Frames and JSON */

2022-04-15T05:28:12Z

Frames and JSON

@@ Line 69: / Line 69: @@
+     }
-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.
 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).

John: /* Initialising the API */

2022-04-15T05:25:59Z

Initialising the API

← Older revision		Revision as of 05:25, 15 April 2022
Line 26:		Line 26:
	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 --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.3 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.

John: /* Initialising the API */

2022-04-14T21:16:29Z

Initialising the API

← Older revision		Revision as of 21:16, 14 April 2022
Line 26:		Line 26:
	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 --rm -d --name telstar-api --network telstar-network -p ~~8011~~:~~8011~~ -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.3 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.3 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.

John: /* Initialising the API */

2022-04-14T21:03:46Z

Initialising the API

← Older revision		Revision as of 21:03, 14 April 2022
Line 26:		Line 26:
	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 8011:8011 -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.3 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.

John at 20:50, 9 April 2022

2022-04-09T20:50:04Z

John: /* Introduction */

2022-04-07T11:30:58Z

Introduction

← Older revision		Revision as of 11:30, 7 April 2022
Line 14:		Line 14:
	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.		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.~~quaratine~~ telstar-util		xattr -d com.apple.quarantine telstar-util

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

← Older revision		Revision as of 20:50, 9 April 2022
Line 1:		Line 1:

	== Introduction ==		== Introduction ==

	Frames can be added to the system using either the Telstar API or by using a plug-in (see [[Implementing ~~Plugins~~]])		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 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.
Line 10:		Line 10:
	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.		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://glasstty.com/wp-content/uploads/2022/04/telstar-util-2.0.zip).		The utility telstar-util can be downloaded from here: (https://glasstty.com/wp-content/uploads/2022/04/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.		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.
Line 53:		Line 53:
	Once authorised, any frame can be retrieved with a simple GET request.		Once authorised, any frame can be retrieved with a simple GET request.

	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
Line 68:		Line 68:
	"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. 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](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 119:		Line 119:

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

	== Adding/Updating a User ==		== 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.		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.		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.

	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.