API Documentation

This documentation covers version 3 of the Flying Sphinx HTTP API. Earlier versions were not documented and only really existed for internal use. This API is used by the Python client, and old releases of the Ruby and NodeJS clients.

Please note: if you don't understand Sphinx, this is not the place to start. This is just an API for managing Sphinx when hosted on Flying Sphinx.

URIs and Content

The API is accessible over HTTPS through https://flying-sphinx.com/api/my/app, and always responds with JSON. The default response is a JSON object with the key status and the value OK. Calls that return additional information are noted as required below.

Authentication and Headers

All API requests should have the following two HTTP headers:

Accept: application/vnd.flying-sphinx-v3+json
X-Flying-Sphinx-Token: FLYING_SPHINX_IDENTIFIER:FLYING_SPHINX_API_KEY

The first provides the API version number (in this case, v3), and the second is the authentication (use your actual identifier and api key values).

It's also preferred that you provide another header which specifies the version and language of the library used to talk to the API. For example, the Python client uses 0.2.0+python, and the Node.js one uses 0.2.0+js. If the code you're writing isn't versioned, then some information identifying you or your project would be nice.

X-Flying-Sphinx-Version: 0.7.0+ruby

Sphinx Configuration

PUT /api/my/app

Parameters:

  • configuration: The contents of a Sphinx configuration file.
  • sphinx_version: Optional indicator of the Sphinx version you wish to use. Allowed values are 1.10, 2.1.0-beta and 2.0.4.

Flying Sphinx will rewrite the provided configuration to set paths appropriately, so don't feel you need to get carried away with exactly where things are located. Index and source names are maintained.

If you are using additional files - for wordforms, exceptions and stopwords - then you'll need to upload those as well.

POST /api/my/app/add_file

Parameters:

  • setting: The setting in question, matching the setting in the Sphinx configuration (eg: wordforms).
  • file_name: The name of the file - and only the name, not the path.
  • content: The contents of the file.

These setting file names are unique for each setting - so, if you have a wordforms file named a.txt that you're using in multiple indices, you only need to upload it once. However, you can also have a stopwords file named a.txt and that is kept separate.

Processing Indices

Because processing Sphinx indices can take quite some time, there's one request to initiate the process, and then another to check on the status and log.

POST /api/my/app/indices

Parameters:

  • indices An optional string of comma-separated names of indices to be processed. If not specified, then the default is all indices.

Response:

  • id: the unique identifier for the process that's just begun.

Once you have the id from the above request, you can then query Flying Sphinx to check the status. Please use this request in moderation - indexing takes at least a few seconds, if not minutes or longer.

GET /api/my/app/indices/:id

Parameters:

  • :id: (in the URI) is the unique identifier for the process.

Response:

  • status: The process status - either PENDING, FINISHED or FAILED.
  • log: The output from Sphinx's indexer (blank unless processing has finished).

Controlling the Daemon

The Sphinx daemon really just has two commands - you can start it, and you can stop it. Both are done through commands with no parameters:

POST /api/my/app/start
POST /api/my/app/stop

If starting the Sphinx daemon fails, the response has a 409 status, and the status in the JSON returned reflects that.

Searching is done by connecting to Sphinx directly - and the address and port are provided through the FLYING_SPHINX_HOST and FLYING_SPHINX_PORT environment variables. You can also access this information through an API call:

GET /api/my/app

Response

  • server: The server to direct search queries to.
  • port: The port to connect through to talk to Sphinx.
  • ssh_server: This is a legacy setting for Heroku's shared database servers. Not useful for anything now.
  • database_port: This is a legacy setting for Heroku's shared database servers. Not useful for anything now.