Skip to content

Building a Custom CLI App

Corey Butler edited this page Apr 7, 2014 · 4 revisions

The Fenix Desktop Application has a free and officially supported console app written in node.js. However; it may be preferable to have a console app available in other languages. If you wish to create your own console application with another technology, this guide will provide you the information necessary to do so. If you create an app, we'd love for you to share with the community. Please let us know!

Overview

Console apps are designed to control Fenix from the command line when it is open. To facilitate this, the desktop app has a built-in web API, available at http://127.0.0.1:33649. It is not a true RESTful API, but it does provide data in JSON format and uses HTTP verbs since it is a simple API. As long as your application can connect to the local machine via HTTP on port 33649, it should be able to communicate with the running Fenix app.

Using the JSON API

The following HTTP endpoints provide all of the functionality Fenix exposes.

GET /server/list

This returns an array of all the servers currently registered on the main screen.

[{
  "name": "My Server",
  "path": "/path/to/site/root",
  "port": 8000,
  "running": true,
  "publicUrl": "https://dfgkljiu.localtunnel.me" // <= Only returned when the server is shared.
},{
  "name": "My Other Server",
  "path": "/path/to/other/site/root",
  "port": 8001,
  "running": true,
  "publicUrl": "https://sdpfljiu.localtunnel.me" // <= Only returned when the server is shared.
}]

PUT /server/{server}/start

This will start a server. If the server does not exist, it will be created and then started.

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number. This endpoint will respond with the configuration details of the new server:

{
  "name": "My Server",
  "path": "/path/to/site/root",
  "port": 8000,
  "running": true
}

If the path cannot be found, the endpoint will return a 410 (Gone) status code to signify that the path is gone/missing. If a port is specified but is already in use, a 409 (Conflict) status code is returned. A 200 (ok) status is only sent when the entire process completes successfully.


PUT /server/{server}/stop

This will stop a server. If the server does not exist, it will respond with a 404 status code.

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number. The endpoint responds with a 404 (Missing) if the server is not found, and 200 (ok) if it is successfully stopped.


PUT /server/{server}/share

This will share a running server and respond with the server configuration:

{
  "name": "My Server",
  "path": "/path/to/site/root",
  "port": 8000,
  "running": true,
  "publicUrl": "https://dfgkljiu.localtunnel.me"
}

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number. If the server cannot be found, a 404 is returned. Otherwise a 200 is returned.


PUT /server/{server}/unshare

This will unshare a server that is currently shared. If this is called against a server that isn't shared, it will still respond with a success code (200).

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number.


PUT /server/{server}/status

Returns a 200 (ok) with the configuration/status of the server:

{
  "name": "My Server",
  "path": "/path/to/site/root",
  "port": 8000,
  "running": true,
  "publicUrl": "https://dfgkljiu.localtunnel.me" // <= Only returned when the server is shared.
}

If the server is not found, a 404 is returned.

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number.


GET /server/{server}/list

This is basically the same as the status endpoint, but reserved for change in the future.

Returns a 200 (ok) with the configuration/status of the server:

{
  "name": "My Server",
  "path": "/path/to/site/root",
  "port": 8000,
  "running": true,
  "publicUrl": "https://dfgkljiu.localtunnel.me" // <= Only returned when the server is shared.
}

If the server is not found, a 404 is returned.

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number.


POST /server

Create a new server. This requires a JSON body to be submitted with the request:

{
  "name": "Descriptive Title",
  "path": "/path/to/site",
  "port": 3000 // <= Optional
}

If the port is not specified, Fenix will automatically find and associate an unused port with the server.


DELETE /server/{server}

This will permanently delete the specified web server.

{server} can be the name of the server, the absolute path of the site root (i.e. /path/to/site), or the port number.

If the server cannot be found or does not exist, the endpoint will respond with a 404.


PUT /close

This forces the desktop application to exit gracefully.


GET /version

Responds with the version of Fenix that is currently running. The result is plain text, not JSON.


There is currently no endpoint for opening a new browser window. If enough people are interested in this functionality, it could be added.

You can’t perform that action at this time.