Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Update documentation locations.

  • Loading branch information...
commit d0291a5cec5d390943a190dd8201db4ce93aae4a 1 parent 98eea9e
@micolous authored
View
4 tollgate/api/urls.py
@@ -27,7 +27,7 @@
# Gets information about a network host by IP.
# Equivalent to the old whatis_ip() API call.
url(
- r'^networkhost/by-ip/(?P<ip_address>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$',
+ r'^networkhost/by-ip/(?P<ip_address>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})/$',
ReadOnlyInstanceModelView.as_view(resource=NetworkHostResource),
dict(online=True),
name='api_whatis_ip'
@@ -48,7 +48,7 @@
# Gets information about a user by IP.
# Equivalent to the old whois_ip() API call.
url(
- r'^user/by-ip/(?P<networkhost__ip_address>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$',
+ r'^user/by-ip/(?P<networkhost__ip_address>\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})/$',
ReadOnlyInstanceModelView.as_view(resource=UserProfileResource),
dict(networkhost__online=True),
name='api_whois_ip'
View
148 tollgate/frontend/templates/frontend/help/api.html
@@ -1,7 +1,8 @@
{% extends "frontend/base.html" %}
+{% load url from future %}
{% comment %}
tollgate api docs page
-Copyright 2008-2011 Michael Farrell <http://micolous.id.au/>
+Copyright 2008-2012 Michael Farrell <http://micolous.id.au/>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
@@ -21,150 +22,9 @@
{% block title %}api{% endblock %}
{% block content %}
-
<p>tollgate has an API allowing for applications to pull some data from the portal system and interact with it.</p>
-<h2>Protocols</h2>
-<p>All protocols require you use an encrypted (HTTPS) connection. Some client libraries require that you install a copy of the certificate in order to establish the connection.</p>
-<p>As of 2.8.3, functions that attempt to get data about "you" will attempt cookie-based authentication first, and if that fails, it will attempt to identify you by your computer's MAC address. Before 2.8.3 it would only try to authenticate you by MAC.</p>
-
-<ul>
- <li><strong>HTTP GET</strong>: This API is available at <code>/api/httpget/&lt;encoding&gt;/&lt;method&gt;/</code>. Arguments are passed by HTTP GET queries. Specifically, these output encodings are supprted:
- <ul>
- <li><strong>CSV</strong> (<code>csv</code>).</li>
- <li><strong>JSON</strong> (<code>json</code>): This output method has a slight quirk, all <code>datetime</code> objects are encoded as a floating point showing the number of seconds since the UNIX epoch (1970-01-01 00:00 UTC). While JavaScript itself has a DateTime object, JSON does not support it.</li>
- <li><strong>Pickle</strong> (<code>pickle</code>). This can be used to implement Python-based applications, however it is recommended you use XMLRPC instead.</li>
- <li><strong>Python</strong> (<code>python</code>). This is the output of the <a href="http://docs.python.org/library/functions.html#repr">repr()</a> function called against the result object. In Python, it is recommended that you use XMLRPC instead. New in v2.8.3.</li>
- </ul>
- </li>
- <li><strong>XMLRPC</strong>: This API is available at <code>/api/xmlrpc/</code>.</li>
-</ul>
-<h2>Structures</h2>
-<p>All of these structures are dicts (Dictionaries). So you would access them like <code>up["first_name"]</code> rather than using a flat array with indexes.</p>
-<dl>
- <dt id="cNetworkHost">NetworkHost</dt>
- <dd>
- <p><code>NetworkHost</code> represents a computer on the network. It has the following keys:</p>
- <ul>
- <li>mac_address (str): The MAC address of the system.</li>
- <li>ip_address (str): The current IPv4 address of the system, or False if the system is offline.</li>
- <li>computer_name (str): The NetBIOS name of the machine.</li>
- <li>first_connection (date): The date when the system first was seen by tollgate.</li>
- <li>online (bool): Whether the system is currently online or not.</li>
- <li>type (str): The type of system this has been detected as. As of 2.8.4, this can be one of several options, described in <a href="https://github.com/micolous/tollgate/blob/master/scraper.dat">scraper.dat</a>. If unknown, it will return pc.</li>
- <li>is_console (bool): Whether the device is a video game console or not. (New in 2.8.4.)</li>
- </ul>
- </dd>
-
- <dt id="cNetworkUsageDataPoint">NetworkUsageDataPoint</dt>
- <dd>
- <p><code>NetworkUsageDataPoint</code> represents usage at a point in time. Unlike other structures, this is encoded as a <code>list</code> (array) to save space. It has two elements:</p>
- <ul>
- <li>0 (datetime): The date and time that this usage point was generated.</li>
- <li>1 (long as str): The amount of bytes of quota used at this point.</li>
- </ul>
- </dd>
-
-
- <dt id="cUsage">Usage</dt>
- <dd>
- <p><code>Usage</code> represents the amount of internet quota available to a user.</p>
- <ul>
- <li>unmetered (bool): True if the user's quota is unmetered, False if it is metered (limited).</li>
- <li>used (long as str): The amount of quota used.</li>
- <li>available (bool): Whether there is internet quota remaining or not.</li>
- <li>total (long as str): The total amount of quota available to a user, in bytes, or False if unmetered.</li>
- <li>resets (int): The amount of times a user has had their quota reset, or False if unmetered.</li>
- <li>remaining (long as str): The amount of bytes remaining on the user's quota, or False if unmetered.</li>
- </ul>
- </dd>
-
-
- <dt id="cUserProfile">UserProfile</dt>
- <dd>
- <p><code>UserProfile</code> represents an encapsulated version of a User with the additional tollgate-related profile data. It has the following keys:</p>
- <ul>
- <li>internet_on (bool): Whether or not internet access is currently enabled for the user.</li>
- <li>username (str): The username of the user.</li>
- <li>forum_uid (long as str): The forum UID of the user. It is recommended that you use this to uniquely identify users, as they may change their username. Returns 0 if the user account is not associated with a forum account. New in v2.8.3.</li>
- <li>first_name (str): The first name of the user. Only returned with <code>whoami()</code>, otherwise is an empty string, as of v2.8.2.</li>
- <li>last_name (str): The last name of the user. Only returned with <code>whoami()</code>, otherwise is an empty string, as of v2.8.2.</li>
- </ul>
- </dd>
-</dl>
-
-<h2>Methods</h2>
-<dl>
- <dt>coffee_ip(ip)</dt>
- <dd>
- <p>Returns a <code>bool</code> indicating whether the user has paid for unlimited coffee or not and is allowed to use the coffee request system.</p>
- <p>Returns <code>False</code> if the IP address is not assigned to a user, the user has been banned from using the coffee request system, or that user hasn't paid for unlimited coffee.</p>
- <p>Returns <code>True</code> if the user has paid for unlimited coffee and is allowed to use the coffee request system. Also implies the user's coffee gland was lost in a tragic accident as a child.</p>
- <p>There is currently no API call to indicate whether the user has paid for <strong>four cooked meals</strong>.</p>
- </dd>
-
- <dt>ping()</dt>
- <dd>
- <p>Always returns True. If it doesn't, then the API is either non-functional, or it is the robot apocolypse.</p>
- </dd>
-
- <dt>usage()</dt>
- <dd>
- <p>Returns a <a href="#cUsage">Usage</a> containing information about remaining quota for either the currently logged in, or if no user is logged in, the current IP address.</p>
- <p>Returns False instead if:</p>
- <ul>
- <li>There was a problem finding the computer's MAC address.</li>
- <li>The computer has not been "owned" by a user of portal.</li>
- <li>There was a problem getting user profile data.</li>
- <li>There is no active event.</li>
- <li>The user has not been signed into this event.</li>
- </ul>
- <p>This function does not require a cookie to work, and does not matter whether or not you have a current session with the web interface. It also will work for hosts that have been remotely signed in.</li>
- <p><strong>Warning:</strong> This function does not give "live" information. It instead looks at a database of previous information so as to not create extra load on the system. This data is updated automatically every 10 minutes. Attempts to get data more frequently that would be futile, and will result in your program being blocked from using the API.</p>
- </dd>
-
- <dt>usage_history()</dt>
- <dd>
- <p>Returns a <a href="#cNetworkUsageDataPoint"><code>NetworkUsageDataPoint<abbr title="list / array">[]</abbr></code></a> representing network usage over the last 36 hours. This can be used to graph network usage of a user over time. You should use this instead of trying to rip the graph from the web interface, so as to reduce resource usage on the server, and so you can make graphs that are native to the look and feel of your application. The data is <em>generally</em> presented in 10 minute intervals, however that may vary so make no assumptions.</p>
- <p>Returns <code>False</code> instead if:</p>
- <ul>
- <li>There was a problem finding the computer's MAC address.</li>
- <li>The computer has not been "owned" by a user of portal.</li>
- <li>There was a problem getting user profile data.</li>
- <li>There is no active event.</li>
- <li>The user has not been signed into this event.</li>
- </ul>
- <p>This method will try to use cookie-based authentication first, and if that fails, will try to get it for the user who owns the computer at this MAC address.</li>
- <p><strong>Warning:</strong> This function does not give "live" information. It instead looks at a database of previous information so as to not create extra load on the system. This data is updated automatically every 10 minutes. Attempts to get data more frequently that would be futile, and will result in your program being blocked from using the API.</p>
- </dd>
+<p>As of 3.0.0, this API has been entirely rewritten to be RESTful, but the same functionality is available. Please see the <a href="{% url 'api_index' %}">autogenerated API documentation</a> for more information.</p>
- <dt>whatis_ip(ip)</dt>
- <dd>
- <p>Returns a <a href="#cNetworkHost">NetworkHost</a> containing information about the specified computer at an IPv4 address, or <code>False</code> if there is no online computer at that IP address.</p>
- <p>Parameters:</p>
- <ol>
- <li>ip (str): A dotted-quad representing the IPv4 address to look up.</li>
- </ol>
-
- <p>Faults if the IP address specified is invalid.</p>
- </dd>
-
- <dt>whoami()</dt>
- <dd>
- <p>Returns a <a href="#cUserProfile">UserProfile</a> containing information about the currently logged in user, or if no person is logged in, the person who owns this MAC address, or <code>False</code> if no user is logged in by either method.</p>
- <p>This function is useful if you are running a program that interacts with tollgate on their computer, and you want to identify them.</p>
- </dd>
-
- <dt>whois_ip(ip)</dt>
- <dd>
- <p>Returns a <a href="#cUserProfile">UserProfile</a> containing information about the owner of the specified computer at an IPv4 address, or <code>False</code> if there is no computer at that IP address, or no user is logged in.</p>
- <p>Parameters:</p>
- <ol>
- <li>ip (str): A dotted-quad representing the IPv4 address to look up.</li>
- </ol>
-
- <p>Faults if the IP address specified is invalid.</p>
- </dd>
-
-</dl>
+<p>Applications designed for older versions of the API will break.
{% endblock %}
Please sign in to comment.
Something went wrong with that request. Please try again.