<p>Evennia makes its database accessible via a REST API found on
<aclass="reference external"href="http://localhost:4001/api">http://localhost:4001/api</a> if running locally with default setup. The API allows you to retrieve, edit and create resources from outside the game, for example with your own custom client or game editor. While you can view and learn about the api in the web browser, it is really
meant to be accessed in code, by other programs.</p>
<p>The API is using <aclass="reference external"href="https://www.django-rest-framework.org/">Django Rest Framework</a>. This automates the process
of setting up <em>views</em> (Python code) to process the result of web requests.
The process of retrieving data is similar to that explained on the
<aclass="reference internal"href="Webserver.html"><spanclass="std std-doc">Webserver</span></a> page, except the views will here return <aclass="reference external"href="https://en.wikipedia.org/wiki/JSON">JSON</a>
<p>The main controlling setting is <codeclass="docutils literal notranslate"><spanclass="pre">REST_FRAMEWORK</span></code>, which is a dict. The keys
<codeclass="docutils literal notranslate"><spanclass="pre">DEFAULT_LIST_PERMISSION</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">DEFAULT_CREATE_PERMISSIONS</span></code> control who may
view and create new objects via the api respectively. By default, users with
<aclass="reference internal"href="Permissions.html"><spanclass="std std-doc">‘Builder’-level permission</span></a> or higher may access both actions.</p>
<p>While the api is meant to be expanded upon, Evennia supplies several operations
out of the box. If you click the <codeclass="docutils literal notranslate"><spanclass="pre">Autodoc</span></code> button in the upper right of the <codeclass="docutils literal notranslate"><spanclass="pre">/api</span></code>
website you’ll get a fancy graphical presentation of the available endpoints.</p>
<p>Here is an example of calling the api in Python using the standard <codeclass="docutils literal notranslate"><spanclass="pre">requests</span></code> library.</p>
<p>In the above example, it now displays the objects inside the “results” array, while it has a “count” value for the number of total objects, and “next” and “previous” links for the next and previous page, if any. This is called <aclass="reference external"href="https://www.django-rest-framework.org/api-guide/pagination/">pagination</a>, and the link displays “limit” and “offset” as query parameters that can be added to the url to control the output.</p>
<p>Other query parameters can be defined as <aclass="reference external"href="https://www.django-rest-framework.org/api-guide/filtering/#filtering">filters</a> which allow you to further narrow the results. For example, to only get accounts with developer permissions:</p>
<p>Now suppose that you want to use the API to create an <aclass="reference internal"href="Objects.html"><spanclass="std std-doc">Object</span></a>:</p>
<p>Here we made a HTTP POST request to the <codeclass="docutils literal notranslate"><spanclass="pre">/api/objects</span></code> endpoint with the <codeclass="docutils literal notranslate"><spanclass="pre">db_key</span></code> we wanted. We got back info for the newly created object. You can now make another request with PUT (replace everything) or PATCH (replace only what you provide). By providing the id to the endpoint (<codeclass="docutils literal notranslate"><spanclass="pre">/api/objects/214</span></code>), we make sure to update the right sword:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>>>> data = {"db_key": "An even SHINIER sword", "db_location": 50}
<p>Overall, reading up on <aclass="reference external"href="https://www.django-rest-framework.org/api-guide/viewsets">Django Rest Framework ViewSets</a> and
other parts of their documentation is required for expanding and
<p>Check out the <aclass="reference internal"href="Website.html"><spanclass="std std-doc">Website</span></a> page for help on how to override code, templates
<li><p>API templates (for the web-display) is located in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/web/api/templates/rest_framework/</span></code> (it must
be named such to allow override of the original REST framework templates).</p></li>
<li><p>Static files is in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/web/api/static/rest_framework/</span></code></p></li>
<li><p>The api code is located in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/web/api/</span></code> - the <codeclass="docutils literal notranslate"><spanclass="pre">url.py</span></code> file here is responsible for
