REST API
classifiers
- GET /api/v1/classifiers/
- Query Parameters
limit (integer) – Number of results to return per page.
name (string) – Filter by classifier name [case insensitive, partial match]
offset (integer) – The initial index from which to return the results.
Example request:
GET /api/v1/classifiers/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "count": 1, "next": "https://example.com", "previous": "https://example.com", "results": [ { "url": "https://example.com", "id": 1, "name": "string" } ] }
- POST /api/v1/classifiers/
Example request:
POST /api/v1/classifiers/ HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string" }
- Status Codes
Example response:
HTTP/1.1 201 Created Content-Type: application/json { "url": "https://example.com", "id": 1, "name": "string" }
- GET /api/v1/classifiers/{id}/
- Parameters
id (integer) – A unique integer value identifying this classifier.
Example request:
GET /api/v1/classifiers/{id}/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "name": "string" }
- PUT /api/v1/classifiers/{id}/
- Parameters
id (integer) – A unique integer value identifying this classifier.
Example request:
PUT /api/v1/classifiers/{id}/ HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string" }
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "name": "string" }
- PATCH /api/v1/classifiers/{id}/
- Parameters
id (integer) – A unique integer value identifying this classifier.
Example request:
PATCH /api/v1/classifiers/{id}/ HTTP/1.1 Host: example.com Content-Type: application/json { "name": "string" }
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "name": "string" }
- DELETE /api/v1/classifiers/{id}/
- Parameters
id (integer) – A unique integer value identifying this classifier.
- Status Codes
204 No Content – No response body
images
- GET /api/v1/images/
This is a read-only model set for
sphinx_hosting.models.SphinxImage
models. It is purposely read-only because images are dependent objects ofsphinx_hosting.models.SphinxPage
instances, and it makes no sense to update them independently.- Query Parameters
archived (boolean) – Filter by archived status
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
orig_path (string) – Filter by original path [case insensitive, partial match]
project (integer) – Filter by project ID
project_classifier (string) – Filter by project classifier name [case insensitive, partial match]
project_machine_name (string) – Filter by project machine name [case insensitive, partial match]
project_title (string) – Filter by project title [case insensitive, partial match]
sphinx_version (string) – Filter by Sphinx version [case insensitive, partial match to start of string]
version (integer) – Filter by version ID
version_number (string) – Filter by version number [case insensitive, exact match]
Example request:
GET /api/v1/images/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "count": 1, "next": "https://example.com", "previous": "https://example.com", "results": [ { "url": "https://example.com", "id": 1, "version": [ "https://example.com" ], "orig_path": "string" } ] }
- GET /api/v1/images/{id}/
This is a read-only model set for
sphinx_hosting.models.SphinxImage
models. It is purposely read-only because images are dependent objects ofsphinx_hosting.models.SphinxPage
instances, and it makes no sense to update them independently.- Parameters
id (integer) – A unique integer value identifying this sphinx image.
Example request:
GET /api/v1/images/{id}/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "version": [ "https://example.com" ], "orig_path": "string" }
pages
- GET /api/v1/pages/
This is a read-only model set for
sphinx_hosting.models.SphinxPage
models. It is purposely read-only because we only want to update pages in the source Sphinx project, not here in the database.Even for our derived fields that we built out of the source, pages have a lot of interdependencies that need to be accounted for while editing.
- Query Parameters
archived (boolean) – Filter by archived status
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
project (integer) – Filter by project ID
project_classifier (string) – Filter by project classifier name [case insensitive, partial match]
project_machine_name (string) – Filter by project machine name [case insensitive, partial match]
project_title (string) – Filter by project title [case insensitive, partial match]
relative_path (string) – Filter by page relative path [case insensitive, partial match]
sphinx_version (string) – Filter by Sphinx version [case insensitive, partial match to start of string]
title (string) – Filter by page title [case insensitive, partial match]
version (integer) – Filter by version ID
version_number (string) – Filter by version number [case insensitive, exact match]
Example request:
GET /api/v1/pages/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "count": 1, "next": "https://example.com", "previous": "https://example.com", "results": [ { "url": "https://example.com", "id": 1, "version": "https://example.com", "title": "string", "relative_path": "string", "content": "string", "orig_body": "string", "body": "string", "orig_local_toc": "string", "local_toc": "string", "orig_global_toc": "string", "searchable": true, "parent": "https://example.com", "next_page": "https://example.com", "previous_page": [ "https://example.com" ] } ] }
- GET /api/v1/pages/{id}/
This is a read-only model set for
sphinx_hosting.models.SphinxPage
models. It is purposely read-only because we only want to update pages in the source Sphinx project, not here in the database.Even for our derived fields that we built out of the source, pages have a lot of interdependencies that need to be accounted for while editing.
- Parameters
id (integer) – A unique integer value identifying this sphinx page.
Example request:
GET /api/v1/pages/{id}/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "version": "https://example.com", "title": "string", "relative_path": "string", "content": "string", "orig_body": "string", "body": "string", "orig_local_toc": "string", "local_toc": "string", "orig_global_toc": "string", "searchable": true, "parent": "https://example.com", "next_page": "https://example.com", "previous_page": [ "https://example.com" ] }
projects
- GET /api/v1/projects/
- Query Parameters
classifier (string) – Filter by project classifier name [case insensitive, partial match]]
description (string) – Filter by project description, [case insensitive, partial match]
limit (integer) – Number of results to return per page.
machine_name (string) – Filter by project machine name, [case insensitive, partial match]
offset (integer) – The initial index from which to return the results.
title (string) – Filter by project title, [case insensitive, partial match]
Example request:
GET /api/v1/projects/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "count": 1, "next": "https://example.com", "previous": "https://example.com", "results": [ { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] } ] }
- POST /api/v1/projects/
Example request:
POST /api/v1/projects/ HTTP/1.1 Host: example.com Content-Type: application/json { "title": "string", "description": "string", "classifiers": [ { "name": "string" } ] }
- Status Codes
Example response:
HTTP/1.1 201 Created Content-Type: application/json { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] }
- GET /api/v1/projects/{id}/
- Parameters
id (integer) – A unique integer value identifying this project.
Example request:
GET /api/v1/projects/{id}/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] }
- PUT /api/v1/projects/{id}/
- Parameters
id (integer) – A unique integer value identifying this project.
Example request:
PUT /api/v1/projects/{id}/ HTTP/1.1 Host: example.com Content-Type: application/json { "title": "string", "description": "string", "classifiers": [ { "name": "string" } ] }
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] }
- PATCH /api/v1/projects/{id}/
- Parameters
id (integer) – A unique integer value identifying this project.
Example request:
PATCH /api/v1/projects/{id}/ HTTP/1.1 Host: example.com Content-Type: application/json { "title": "string", "description": "string", "classifiers": [ { "name": "string" } ] }
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] }
- DELETE /api/v1/projects/{id}/
- Parameters
id (integer) – A unique integer value identifying this project.
- Status Codes
204 No Content – No response body
- GET /api/v1/projects/{id}/latest_version/
- Parameters
id (integer) – A unique integer value identifying this project.
Example request:
GET /api/v1/projects/{id}/latest_version/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "title": "string", "machine_name": "string", "description": "string", "related_links": [ "https://example.com" ], "classifiers": [ { "url": "https://example.com", "id": 1, "name": "string" } ], "versions": [ "https://example.com" ] }
schema
- GET /api/v1/schema/
OpenApi3 schema for this API. Format can be selected via content negotiation.
YAML: application/vnd.oai.openapi
JSON: application/vnd.oai.openapi+json
- Query Parameters
format (string) –
Example request:
GET /api/v1/schema/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json {}
version
- POST /api/v1/version/import/
This is the view to use to upload our sphinx tarballs. It uploads to a temporary directory that disappears at the end of this view.
To upload a file, you must submit as form-data, with a single file key named
file
, with theContent-Disposition
header like so:Content-Disposition: attachment;filename=yourdocs.tar.gz
The filename you pass in the
Content-Disposition
header does not matter and is not used; set it to whatever you want.Example:
To upload a file with
curl
to the endpoint for this view:curl \ -XPOST \ -H "Authorization: Token __THE_API_TOKEN__" \ -F 'file=@path/to/yourdocs.tar.gz' \ https://sphinx-hosting.example.com/api/v1/version/import/
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "file": "https://example.com" }
versions
- GET /api/v1/versions/
Users can get, list and delete
sphinx_hosting.models.Version
objects, but they can’t create or update them the normal Django way.- Query Parameters
archived (boolean) – Filter by archived status
limit (integer) – Number of results to return per page.
offset (integer) – The initial index from which to return the results.
project (integer) –
project_classifier (string) – Filter by project classifier name [case insensitive, partial match]
project_machine_name (string) – Filter by project machine name [case insensitive, partial match]
project_title (string) – Filter by project title [case insensitive, partial match]
sphinx_version (string) – Filter by Sphinx version [case insensitive, partial match to start of string]
version (string) –
version_number (string) – Filter by version number [case insensitive, exact match]
Example request:
GET /api/v1/versions/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "count": 1, "next": "https://example.com", "previous": "https://example.com", "results": [ { "url": "https://example.com", "id": 1, "project": "https://example.com", "version": "string", "sphinx_version": "string", "archived": true, "head": "https://example.com", "pages": [ "https://example.com" ], "images": [ "https://example.com" ] } ] }
- GET /api/v1/versions/{id}/
Users can get, list and delete
sphinx_hosting.models.Version
objects, but they can’t create or update them the normal Django way.- Parameters
id (integer) – A unique integer value identifying this version.
Example request:
GET /api/v1/versions/{id}/ HTTP/1.1 Host: example.com
- Status Codes
200 OK –
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "url": "https://example.com", "id": 1, "project": "https://example.com", "version": "string", "sphinx_version": "string", "archived": true, "head": "https://example.com", "pages": [ "https://example.com" ], "images": [ "https://example.com" ] }
- DELETE /api/v1/versions/{id}/
Users can get, list and delete
sphinx_hosting.models.Version
objects, but they can’t create or update them the normal Django way.- Parameters
id (integer) – A unique integer value identifying this version.
- Status Codes
204 No Content – No response body