Self hosted FLOSS fitness/workout, nutrition and weight tracker
Move the API documentation to the docs repo
Roland Geider1c00d8ea4a49
diff --git a/wger/core/templates/user/api_key.html b/wger/core/templates/user/api_key.htmlindex 7edfe8fa0..cd03c3a46 100644--- a/wger/core/templates/user/api_key.html+++ b/wger/core/templates/user/api_key.html@@ -5,53 +5,53 @@{% block content %}-{% with url='/api/v2/' %}-<p>{% blocktranslate %}Generate an API key if you want to interact with wger via-the <a href="{{url}}" rel="nofollow">REST API</a> it provides (for-public resources such as the exercises or ingredients, you don't need to provide-anything). You must pass this information in the header in the format shown below.{% endblocktranslate %}-{% endwith %}--<p>{% blocktranslate %}For security reasons, you should only access the API via HTTPS.{% endblocktranslate %}</p>-<div class="card mb-4 {% if token %}text-white bg-success{% else %}bg-light{% endif %}" >- <div class="card-header">- {% translate "Your API key" %}+ <p>+ Please use JWT authentication if possible. More details in the+ <a href="https://wger.readthedocs.io/en/latest/">online documentation</a>.+ </p>++ <div class="card mb-4 {% if token %}text-white bg-success{% else %}bg-light{% endif %}">+ <div class="card-header">+ {% translate "Your API key" %}+ </div>+ <div class="card-body">+ {% if token %}+ <strong>{{ token.key }}</strong>+ {% else %}+ <em>{% translate "You have no API key yet" %}</em>+ {% endif %}+ </div></div>- <div class="card-body">- {% if token %}- <strong>{{token.key}}</strong>- {% else %}- <em>{% translate "You have no API key yet" %}</em>- {% endif %}- </div>-</div>-<h5>In the request header</h5>-<pre>-Authorization: Token {% if token %}{{token.key}}{% else %}1234567890abcde...{% endif %}-</pre>+ <p>+ Pass "Token {% if token %}{{ token.key }}{% else %}1234567890abcde...{% endif %}" in the+ <code>Authorization</code> header to use it+ </p>-<h5>Example with curl</h5>-<pre>-curl -X GET https://wger.de/api/v2/workout/ \- -H 'Authorization: Token {% if token %}{{token.key}}{% else %}1234567890abcde...{% endif %}'+ <p>Example with curl:</p>+ <pre>+curl -X GET https://wger.de/api/v2/routine/ \+ -H 'Authorization: Token {% if token %}{{ token.key }}{% else %}1234567890abcde...{% endif %}'</pre>{% endblock %}{% block sidebar %}-<h4>{% translate "Options" %}</h4>--<p>-{% if token %}- <a href="{% url 'core:user:api-key' %}?new_key=true" class="btn btn-block btn-light">{% translate 'Delete current API key and generate new one' %}</a>-{% else %}- <a href="{% url 'core:user:api-key' %}?new_key=true" class="btn btn-block btn-light">{% translate 'Generate new API key' %}</a>-{% endif %}-</p>--<p>- <a href="{% url 'software:api' %}" class="btn btn-block btn-light">{% translate 'Documentation' %}</a>-</p>+ <h4>{% translate "Options" %}</h4>++ <p>+ {% if token %}+ <a href="{% url 'core:user:api-key' %}?new_key=true"+ class="btn btn-block btn-light">{% translate 'Delete current API key and generate new one' %}</a>+ {% else %}+ <a href="{% url 'core:user:api-key' %}?new_key=true"+ class="btn btn-block btn-light">{% translate 'Generate new API key' %}</a>+ {% endif %}+ </p>++ <p>+ <a href="{% url 'software:api' %}"+ class="btn btn-block btn-light">{% translate 'Documentation' %}</a>+ </p>{% endblock %}diff --git a/wger/software/templates/api.html b/wger/software/templates/api.htmlindex c09a57e4d..096c634d1 100644--- a/wger/software/templates/api.html+++ b/wger/software/templates/api.html@@ -17,224 +17,11 @@<li><a href="{% url 'schema' %}">Download openAPI 3 schema file</a></li></ul>-- <h3>Authentication</h3>- <p>- Public endpoints, such as the list of exercises or the ingredients can be- accessed without authentication. For user owned objects such as- workouts, you need to authenticate.</p>-- <h5>JWT Authentication</h5>- <p>- This is the suggested way. You generate a temporary token which you send in- the header with each request that needs authorization- </p>-- <h6>1. Get the tokens</h6>- <p>- Send your username and password to the <code>/api/v2/token</code>- endpoint, you will get an <code>access</code> and a <code>refresh</code> token- back.- </p>- <pre>-result = requests.post(- 'https://wger.de/api/v2/token',- data={'username': 'user', 'password': 'admin'}-)-access_token = result.json()['access']-refresh_token = result.json()['refresh']--print(result.json())->>> {'refresh': 'eyJhbGciOiJIUzI1...', 'access': 'eyJhbGciOiJIUzI...'}- </pre>-- <h6>2. Authenticate</h6>- <p>- Pass the access token in the Authorization header as <code>"Bearer: your-token"</code>- </p>- <pre>-result = requests.get(- 'https://wger.de/api/v2/workout/',- headers={'Authorization': f'Bearer {access_token}'}-)--print(result.json())->>> {'count': 5, 'next': None, 'previous': None, 'results': [{'id':.....-</pre>-- <p>- Additionally, you can send the access token to <code>/token/verify</code>- endpoint to verify it.- </p>-- <pre>-result = requests.post('https://wger.de/api/v2/token/verify', data={'token': access_token})- </pre>-- <h6>3. Refresh</h6>- <p>- When this short-lived access token expires, you can use the longer-lived- <code>refresh</code> token to obtain another access token.- </p>- <pre>-result = requests.post(- 'https://wger.de/api/v2/token/refresh/',- data={'refresh': refresh_token}-)-token = result.json()--print(token)->>> {'access': 'eyJhbGciOiJI...'}--</pre>-- <h5>Permanent Token</h5>- <p>- Note that this method is not recommended.- You can also pass a permanent token in the header to authenticate, but this- method should be considered deprecated. If you want to generate a token- <a href="{% url 'core:user:api-key' %}">use this page</a>.- </p>-- <h6>Username and password</h6>- <p>- You can also get a token from the <code>login</code> endpoint.- Send a username and password in a POST request. IF the user doesn't- currently have a token, a new one will be generated for you- </p>--- <div class="container">- <div class="row">- <div class="col-6">- <h4>Public endpoints</h4>- <ul>- <li>daysofweek</li>- <li>equipment</li>- <li>exercise</li>- <li>exercisealias</li>- <li>exercisecategory</li>- <li>exercisecomment</li>- <li>exerciseimage</li>- <li>exercisebaseinfo</li>- <li>ingredient</li>- <li>ingredientinfo</li>- <li>ingredienttoweightunit</li>- <li>language</li>- <li>license</li>- <li>muscle</li>- <li>setting-repetitionunit</li>- <li>setting-weightunit</li>- <li>variation</li>- <li>weightunit</li>- </ul>- </div>- <div class="col-6">- <h4>Private endpoints</h4>- <ul>- <li>day</li>- <li>gallery</li>- <li>meal</li>- <li>mealitem</li>- <li>nutritiondiary</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>- </div>--- <h3>Format negotiation</h3>- <p>- At the moment only JSON and the browsable HTML view are supported. That- means that you can use the same endpoints from your browser or a client.- Because of this, for the majority of REST clients it will not be- necessary to explicitly set the format, but you have the following options:- </p>- <ul>- <li>Set the <strong>Accept</strong> header:- <ul>- <li><code>application/json</code></li>- <li>- <code>application/json; indent=4</code> - useful for debugging, will- indent the result- </li>- <li>- <code>text/html</code> - browsable HTML view- </li>- </ul>- </li>- <li>- Set the format <strong>directly in the URL</strong>:- <ul>- <li>- <code>/api/v2/<endpoint>.json/</code>- </li>- <li>- <code>/api/v2/<endpoint>/?format=json</code>- </li>- <li>- <code>/api/v2/<endpoint>.api/</code> - browsable HTML view- </li>- </ul>- </li>- </ul>--- <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.+ For information on how to authenticate, filter, etc., please consult the online+ docs at <a href="https://wger.readthedocs.io/en/latest/">https://wger.readthedocs.io/en/latest/</a></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,- the filters will be AND-joined:- <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>- Note that it is not currently possible to specify more than one value, e.g.- category 1 or 2. The <strong>only</strong> exception to this is the exercises endpoint,- there it is possible to OR different values, e.g. <code>?muscles=2,7</code>- which will search for exercises that train muscle 2 OR 7.- </p>- <p>Some examples:</p>-- <ul>- <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 with barbells: <code>api/v2/exercise/?muscles=1&equipment=3</code>- </li>- </ul>---{% endblock %}@@ -246,5 +33,7 @@ print(token)similar drop us a line first!</div>- <p><a href="{% url 'core:user:api-key' %}" class="btn btn-block btn-light">Generate API KEY</a>+ <a href="{% url 'core:user:api-key' %}" class="btn btn-block btn-light">+ Generate permanent API KEY+ </a>{% endblock %}