<pclass="last">You are reading an old version of the Evennia documentation. <ahref="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
<h1>Evennia REST API<aclass="headerlink"href="#evennia-rest-api"title="Permalink to this headline">¶</a></h1>
<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="doc 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>
data for the resource you want. You can also <em>send</em> such JSON data
in order to update the database from the outside.</p>
<sectionid="usage">
<h2>Usage<aclass="headerlink"href="#usage"title="Permalink to this headline">¶</a></h2>
<p>To activate the API, add this to your settings file.</p>
<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="doc 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="doc std std-doc">Object</span></a>:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>>>> data = {"db_key": "A shiny sword"}
<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}
{"db_key": "An even SHINIER sword", "id": 214, "db_location": 50, ...}
</pre></div>
</div>
<p>In most cases, you won’t be making API requests to the backend with Python,
but with Javascript from some frontend application.
There are many Javascript libraries which are meant to make this process
easier for requests from the frontend, such as <aclass="reference external"href="https://github.com/axios/axios">AXIOS</a>, or using
the native <aclass="reference external"href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API">Fetch</a>.</p>
</section>
<sectionid="customizing-the-api">
<h2>Customizing the API<aclass="headerlink"href="#customizing-the-api"title="Permalink to this headline">¶</a></h2>
<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
customizing the API.</p>
<p>Check out the <aclass="reference internal"href="Website.html"><spanclass="doc std std-doc">Website</span></a> page for help on how to override code, templates
and static files.</p>
<ulclass="simple">
<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
collecting all view-classes.</p></li>
</ul>
<p>Contrary to other web components, there is no pre-made <aclass="reference external"href="http://urls.py">urls.py</a> set up for
<codeclass="docutils literal notranslate"><spanclass="pre">mygame/web/api/</span></code>. This is because the registration of models with the api is
strongly integrated with the REST api functionality. Easiest is probably to
copy over <codeclass="docutils literal notranslate"><spanclass="pre">evennia/web/api/urls.py</span></code> and modify it in place.</p>
<pclass="last">You are reading an old version of the Evennia documentation. <ahref="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
