{% extends 'base.html' %}

{% block title %}Wheelodex — JSON API{% endblock %}

{% block content %}
<div class="breadcrumbs">
    <a href="{{url_for('.index')}}">Wheelodex</a>
    &#xBB; JSON API
</div>

<div class="search-header">
    <form action="{{url_for('.search_projects')}}" method="GET">
        <input type="text" name="q" placeholder="Search Projects"/>
    </form>
</div>

<p>Wheelodex provides endpoints exposing some of its information as JSON:</p>

<dl>

<dt><code>/json/projects/<span class="url-placeholder">:project</span></code> (<a href="{{url_for('.project_json', project='requests')}}">[example]</a>)</dt>

<dd>
    <p>Returns a list of all wheels for the given project currently registered
    in Wheelodex, organized by version.  Each wheel entry includes a
    <code>has_data</code> key indicating whether the contents of the given
    wheel have been analyzed yet.</p>

    <p>Example response:</p>

<pre>{
    "1.0.0": [
        {
            "filename": "example-1.0.0-py3-none-any.whl",
            "has_data": true,
            "href": "/json/wheels/example-1.0.0-py3-none-any.whl.json"
        },
        {
            "filename": "example-1.0.0-py2-none-any.whl",
            "has_data": false,
            "href": "/json/wheels/example-1.0.0-py2-none-any.whl.json"
        }
    ]
}
</pre>
</dd>

<dt><code>/json/projects/<span class="url-placeholder">:project</span>/data</code> (<a href="{{url_for('.project_data_json', project='requests')}}">[example]</a>)</dt>

<dd>
    <p>Returns all known data about one of the project's wheels.  If the
    project has multiple wheels, the one from the latest version that is likely
    to apply to the most users is chosen.  Wheels whose contents have been
    analyzed are preferred over wheels that haven't been analyzed.</p>

    <p>The schema of the returned data is the same as for
    <code>/json/wheels/<span class="url-placeholder">:wheel</span>.json</code>
    (see below).<p>

    <p>Responds with a 404 if the project doesn't have any wheels.</p>
</dd>

<dt><code>/json/projects/<span class="url-placeholder">:project</span>/rdepends</code> (<a href="{{url_for('.project_rdepends_json', project='requests')}}">[example]</a>)</dt>

<dd>
    <p>Returns a paginated list (100 entries per page) of the projects that
    depend on the given project.</p>

    <p>Example response:</p>
<pre>{
    "items": [
        {
            "href": "/json/projects/sample",
            "name": "sample"
        }
        {
            "href": "/json/projects/uses-your-project",
            "name": "Uses.Your.Project"
        },
        &#x2026;
    ],
    "links": {
        "next": "/json/projects/example/rdepends?page=2",
        "prev": null
    },
    "total": 123
}
</pre>
</dd>

<dt><code>/json/wheels/<span class="url-placeholder">:wheel</span>.json</code>{% if example_wheel != None %} (<a href="{{url_for('.wheel_json', wheel=example_wheel.filename)}}">[example]</a>){% endif %}</dt>
<dd>
    <p>Returns all known data about the given wheel.  <code><span
    class="url-placeholder">:wheel</span></code> must be the entire wheel
    filename, including the "<code>.whl</code>" extension.</p>

    <p>The returned structure contains the following keys:<p>

    <dl>
        <dt><code>"pypi"</code></dt>
        <dd>Data about the wheel acquired from PyPI</dd>

        <dt><code>"data"</code></dt>
        <dd>(Only present if the wheel has been analyzed) Data about the wheel,
        produced by <a
        href="https://pypi.org/project/wheel-inspect/">wheel-inspect</a></dd>

        <dt><code>"wheelodex"</code></dt>
        <dd>(Only present if the wheel has been analyzed) An object containing
        two keys: <code>"processed"</code>, the timestamp of when the wheel was
        analyzed, and <code>"wheel_inspect_version"</code>, the version of
        wheel-inspect used to analyze the wheel</dd>

        <dt><code>"errored"</code></dt>
        <dd>A boolean (only present if <code>true</code>) indicating whether
        any errors occurred while trying to process the wheel</dd>
    </dl>
</dd>

</dl>

{% endblock %}