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:

201 Created –

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 of sphinx_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 of sphinx_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"
                }
            ],
            "latest_version": "https://example.com",
            "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:

201 Created –

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"
        }
    ],
    "latest_version": "https://example.com",
    "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"
        }
    ],
    "latest_version": "https://example.com",
    "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"
        }
    ],
    "latest_version": "https://example.com",
    "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"
        }
    ],
    "latest_version": "https://example.com",
    "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"
        }
    ],
    "latest_version": "https://example.com",
    "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 the Content-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

REST API

classifiers

images

pages

projects

related-links

schema

version

versions