{% extends "base.html" %}
{% load staticfiles %}
{% load wger_extras %}


{% block title %}REST API{% endblock %}

{% block content %}
<p>wger Workout Manager provides a full REST API to all database
objects: <a href="/api/v1/?format=json" rel="nofollow">https://wger.de/api/v1/</a></p>

<p>The API uses HATEOAS, so you should be able to browse
through the necessary endpoints without having to consult an extensive
documentation. At the moment, the API only supports read operations, but
support for full POST/PUT/DELETE/PATCH is planned for the near future.</p>

<p>You should always use HTTPS if possible when communicating with the server.</p>


<h3>Authentication</h3>
<p>Public endpoints, such as the list of exercises or the
ingredients can be accessed without authentication. For <strong>user owned
objects such as workouts, you need to generate an API KEY</strong> and pass
it along with the username either in the header or in form of GET parameters.
See the link on the sidebar for details.</p>


<div class="ym-grid linearize-level-1">
    <div class="ym-g50 ym-gl">
        <h4>Public endpoints</h4>
        <ul>
            <li>daysofweek</em></li>
            <li>equipment</li>
            <li>exercise</li>
            <li>exercisecategory</li>
            <li>exercisecomment</li>
            <li>exerciseimage</li>
            <li>ingredient</li>
            <li>ingredienttoweightunit</li>
            <li>language</li>
            <li>muscle</li>
            <li>weightunit</li>
            <li>license</li>
        </ul>
    </div>
    <div class="ym-g50 ym-gl">
        <h4>Private endpoints</h4>
        <ul>
            <li>day</li>
            <li>meal</li>
            <li>mealitem</li>
            <li>nutritionplan</li>
            <li>schedule</li>
            <li>schedulestep</li>
            <li>set</li>
            <li>setting</li>
            <li>userprofile</li>
            <li>weightentry</li>
            <li>workout</li>
            <li>workoutlog</li>
        </ul>
    </div>
</div>



<h3>Fetching Data</h3>
<!--
Many of the explanations are taken from
https://django-tastypie.readthedocs.org/en/latest/interacting.html
-->

<p>If you explore the API with a browser, you will need to add a <code>?format=json</code>
to these URLs. You don't need to do this when using other tools or when explicitly
sending the Accept header to "application/json".</p>

<h4>Api-Wide</h4>
<code>
curl https://wger.de/api/v1/ | python -m json.tool
</code>

<p>This lists out all the different resources available. Each one is listed by
the "resource_name" and provides the "list_endpoint" and the schema for the
resource. Note that these links try to direct you to other parts of the API,
to make exploration/discovery easier.</p>


<h4>Getting A Collection Of Resources</h4>
<code>
curl https://wger.de/api/v1/exercise/ | python -m json.tool
curl https://wger.de/api/v1/exercise/schema/ | python -m json.tool
</code>


<ul>
    <li>By default, you get a paginated set of objects</li>
    <li>In "meta", you get a "previous" and "next". If available, these are URIs to the previous and next pages.</li>
    <li>?limit=0 returns all resources, without pagination.</li>
    <li>You get a list of resources/objects under the "objects" key.</li>
    <li>Each resources/object has a "resource_uri" field that points to the detail view for that object.</li>
    <li>Foreign keys are represented as URIs.</li>
</ul>


<p>You can also filter the resources, the syntax is the same as the Django ORM.
Take a look at the <a href="https://docs.djangoproject.com/en/1.6/ref/models/querysets/#field-lookups">field
lookup documentation</a> for more details on how to use the individual lookups.
The following field lookups are supported, but don't always make sense
for all fields (in that case you'll just get an emtpy result). Alternatively you
can just specify the IDs you want or provide an offset.</p>

<ul>
    <li>exact/iexact</li>
    <li>contains/icontains</li>
    <li>in</li>
    <li>gt/gte</li>
    <li>lt/lte</li>
    <li>startswith/istartswith</li>
    <li>endswith/iendswith</li>
    <li>range</li>
    <li>isnull</li>
    <li>year</li>
    <li>month</li>
    <li>day</li>
    <li>week_day</li>
    <li>hour</li>
    <li>minute</li>
    <li>second</li>
</ul>

<p>Some examples:</p>

<code>
curl https://wger.de/api/v1/exercise/?name__istartswith=bicep | python -m json.tool
curl https://wger.de/api/v1/exercise/?status__in=2,4,5 | python -m json.tool
curl https://wger.de/api/v1/exercise/?language=1 | python -m json.tool
curl https://wger.de/api/v1/exercise/?category__name__istartswith=ba | python -m json.tool
curl https://wger.de/api/v1/exercise/1/ | python -m json.tool

# quoting needed for bash
curl "https://wger.de/api/v1/exercise/set/1;3/" | python -m json.tool
curl "https://wger.de/api/v1/exercise/?offset=20&limit=20" | python -m json.tool
</code>

<p></p>
{% endblock %}



{% block sidebar %}
<div class="alert alert-info" style="margin-top:1em;">
This is also new for us, if you plan on using the API,
<a href="https://groups.google.com/group/wger">we'd love to hear from you</a>.
</div>

<p><a href="/api/v1/?format=json" class="btn btn-block" rel="nofollow">Browse the API</a></p>
<p><a href="{% url 'core:api-key' %}" class="btn btn-block">Generate API KEY</a></p>
{% endblock %}
