Self hosted FLOSS fitness/workout, nutrition and weight tracker
Update the documentation for the new REST API
Roland Geider8115bb8ddae4
diff --git a/wger/core/templates/rest_framework/api.html b/wger/core/templates/rest_framework/api.htmlindex b7cae2780..6a82c4954 100644--- a/wger/core/templates/rest_framework/api.html+++ b/wger/core/templates/rest_framework/api.html@@ -17,9 +17,12 @@{# #}{% block breadcrumbs %}<ol class="breadcrumb">+ <li>+ <a href="{% url 'software:api' %}">Api Documentation</a>+ </li>{% for breadcrumb_name, breadcrumb_url in breadcrumblist %}{% if not forloop.last %}- <li class="active">+ <li><a href="{{ breadcrumb_url }}">{{ breadcrumb_name }}</a></li>{% else %}@@ -118,7 +121,7 @@{% with form=raw_data_post_form %}<form action="{{ request.get_full_path }}" method="POST" class="form-horizontal" role="form"><fieldset>- {% render_form_fields form 'Send' %}+ {% render_form_fields form 'POST' %}</fieldset></form>{% endwith %}diff --git a/wger/software/templates/api.html b/wger/software/templates/api.htmlindex 88cec5310..5aea5115f 100644--- a/wger/software/templates/api.html+++ b/wger/software/templates/api.html@@ -7,22 +7,15 @@{% 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>+objects: <a href="/api/v2/" rel="nofollow">https://wger.de/api/v2/</a></p><h3>Authentication</h3><p>Public endpoints, such as the list of exercises or theingredients can be accessed without authentication. For <strong>user ownedobjects 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>+it in the header, see the link on the sidebar for details.</p>+<p>You should always use HTTPS if possible when communicating with the server.</p><div class="row">@@ -65,86 +58,148 @@ See the link on the sidebar for details.</p><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><pre>-curl https://wger.de/api/v1/exercise/ | python -m json.tool-curl https://wger.de/api/v1/exercise/schema/ | python -m json.tool+# Api-Wide+/api/v2/++# Object detail view+/api/v2/<endpoint>/<id>/</pre>+<p>+ This lists out all the different resources available. If you visit the+ link with a browser, you'll get a human-browsable HTML version of the+ contents. If you are logged in, you can use the built in form to try+ different requests (POST, PATCH, etc.)+</p>++<p>+ You can do a <code>OPTIONS /api/v2/<endpoint>/</code> to get more+ information on the endpoint such as the accepted formats. It also outputs+ a listing with all the resource's fields, their type (date, int, etc.) and+ a short description. This is more easier done when using the browseable+ version.+</p>++++<h3>Miscellaneous operations</h3>+<h4>Ordering</h4>+<p>+ Simply use <code>?ordering=<fieldname></code> to order by that field.+ You can also specify more than one field name, just give it a list separated+ by commas <code>?ordering=<field1>,<field2></code>. To reverse+ the order use like in django a <code>-</code> in front of the field.+</p>++++<h4>Pagination</h4>+<p>+ By default all results are paginated by 20 elements per page. If you want to+ change this value, add a <code>?limit=<xxx></code> to your query.+ You will find in the answer JSON the <code>next</code> and <code>previous</code>+ keywords with links to the next or previous result pages.+</p>++++<h4>Filtering resources</h4>+<p>+ You can easily filter all resources by specifying the filter queries in the+ URL: <code>?<fieldname>=<value></code>, combinations are possible,+ just separate the filters with a comma: <code>?<f1>=<v1>,<f2>=<v2></code>.+ Please note that for boolean values you must pass 'False' or 'True' other+ values, e.g. 1, 0, false, etc. will be ignored. Like with not filtered queries,+ your objects will be available under the 'results' key.+</p>+<p>+ It is not possible to specify more than one value, e.g. category 1 or 2.+ To achieve this, just repeat the filter. See example below.+</p>+<p>Some examples:</p><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>+ <li>All exercises in German: <code>api/v2/exercise/?language=1</code></li>+ <li>'Main' image for all exercises: <code>api/v2/exerciseimage/?is_main=True</code></li>+ <li>Exercises that train the biceps or the triceps:+ <code>api/v2/exercise/?muscles=1&muscles=5</code>+ </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>+<h3>Special endpoints</h3>+<p>+ The following endpoints provide additional information, comfort functions, etc.:+</p>+<div class="row">+ <div class="col-md-1">+ <code>api/v2/workout/<id>/canonical_representation/</code>+ </div>+</div>+<div class="row">+ <div class="col-md-offset-1 col-md-10">+ This is a complete representation of a workout, including all objects+ like workout days, exercises, etc. This form used by the django application+ to render workouts or perform other operations. The data is cached so,+ accessing or using is faster than performing many different requests.+ </div>+</div>-<pre>-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+<div class="row" style="margin-top: 1em;">+ <div class="col-md-1">+ <code>api/v2/exerciseimage/<id>/thumbnails/</code>+ </div>+</div>+<div class="row">+ <div class="col-md-offset-1 col-md-10">+ Returns a list of available thumbnails for this image. The 'settings' key+ refers to the settings used by the thumbnailing application to generate+ that image. The special key 'original' is simply a downloadable link to+ the original image used.+ </div>+</div>+-# Note: the "| python -m json.tool" is only for formatting the returned JSON-</pre>+<div class="row" style="margin-top: 1em;">+ <div class="col-md-1">+ <code>api/v2/nutritionplan/<id>/nutritional_values/</code><br>+ <code>api/v2/meal/<id>/nutritional_values/</code><br>+ <code>api/v2/mealitem/<id>/nutritional_values/</code>+ </div>+</div>+<div class="row">+ <div class="col-md-offset-1 col-md-10">+ Returns the total nutritional values for a nutritional plan, a meal or+ an individual meal item. The nutritional plan lists this under the+ 'total' key, the other two return a flat list.++ The nutritional plan also returns under the 'per_kg' key the calculated+ values of grams per user body weight (if available) and 'percent' lists+ the percent each macronutrient contributes to the total calories.+ </div>+</div>++++<h3>/api/v1</h3>+<div class="panel panel-warning">+ <div class="panel-heading">+ <h3 class="panel-title">Deprecation warning</h3>+ </div>+ <div class="panel-body">+ The first API supported only read operations. Due to different reasons+ it is being deprecated and should not be used anymore, it will be+ deactivated on June 2015.+ </div>+</div>+<p>+</p>-<p></p>{% endblock %}@@ -155,6 +210,6 @@ 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 btn-default" rel="nofollow">Browse the API</a></p>+<p><a href="/api/v2/" class="btn btn-block btn-default" rel="nofollow">Browse the API</a></p><p><a href="{% url 'core:api-key' %}" class="btn btn-block btn-default">Generate API KEY</a></p>{% endblock %}