commit 9c788a8897fa394baf4c66b00b1703d7ca84b8b3 Author: Karsten Loesing karsten.loesing@gmx.net Date: Fri Oct 11 18:14:39 2013 +0200
Move methods part above document specifications. --- web/index.html | 366 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 183 insertions(+), 183 deletions(-)
diff --git a/web/index.html b/web/index.html index f663280..a648b8d 100755 --- a/web/index.html +++ b/web/index.html @@ -68,6 +68,189 @@ changes. <p>The Onionoo API is described by resource types and available methods below.</p> <br> +<a name="methods"></a> +<h3><a href="#methods" class="anchor">Methods</a></h3> +<p>The following methods each return a single document containing zero or +more relay and/or bridge documents.</p> +<table border="0" cellpadding="4" cellspacing="0" summary=""> +<colgroup> +<col width="150"> +<col width="850"> +</colgroup> +<tr> +<td><b>GET summary</b></td> +<td>Return summaries of all relays and bridges that are currently running +or that have been running in the past week. +</td> +</tr> +<tr> +<td><b>GET details</b></td> +<td>Return details of all relays and bridges that are currently running +or that have been running in the past week. +</td> +</tr> +<tr> +<td><b>GET bandwidth</b></td> +<td>Return bandwidth documents of all relays and bridges that are +currently running or that have been running in the past week. +</td> +</tr> +<tr> +<td><b>GET weights</b></td> +<td>Return weights documents of all relays and bridges that are currently +running or that have been running in the past week. +</td> +</tr> +</table> +<p>Each of the methods above can be parameterized to select only a subset +of relay and/or bridge documents to be included in the response. +If multiple parameters are specified, they are combined using a logical +AND operation, meaning that only the intersection of relays and bridges +matching all parameters is returned. +If the same parameter is specified more than once, only the first +parameter value is considered. +</p> +<table border="0" cellpadding="4" cellspacing="0" summary=""> +<colgroup> +<col width="150"> +<col width="850"> +</colgroup> +<tr><td><b>type</b></td><td>Return only relay (parameter value +<b>relay</b>) or only bridge documents (parameter value +<b>bridge</b>). +Parameter values are case-insensitive. +</td></tr> +<tr><td><b>running</b></td><td>Return only running (parameter value +<b>true</b>) or only non-running relays and/or bridges (paramter value +<b>false</b>). +Parameter values are case-insensitive. +</td></tr> +<tr><td><b>search</b></td><td>Return only relays with the parameter value +matching (part of a) nickname, (possibly $-prefixed) beginning of a +fingerprint, or beginning of an IP address, and bridges with (part of a) +nickname or (possibly $-prefixed) beginning of a hashed fingerprint. +Searches for beginnings of IP addresses are performed on textual +representations of canonical IP address forms, so that searches using CIDR +notation or non-canonical forms will return empty results. +Searches are case-insensitive. +If multiple search terms are given, separated by spaces, the intersection +of all relays and bridges matching all search terms will be returned. +Full fingerprints should always be hashed using SHA-1, regardless of +searching for a relay or a bridge, in order to not accidentally leak +non-hashed bridge fingerprints in the URL. +</td></tr> +<tr><td><b>lookup</b></td><td>Return only the relay with the parameter +value matching the fingerprint or the bridge with the parameter value +matching the hashed fingerprint. +Fingerprints should always be hashed using SHA-1, regardless of looking up +a relay or a bridge, in order to not accidentally leak non-hashed bridge +fingerprints in the URL. +Lookups only work for full fingerprints or hashed fingerprints consisting +of 40 hex characters. +Lookups are case-insensitive. +</td></tr> +<tr><td><b>country</b></td><td>Return only relays which are located in the +given country as identified by a two-letter country code. +Filtering by country code is case-insensitive. +</td></tr> +<tr><td><b>as</b></td> +<td>Return only relays which are located in the +given autonomous system (AS) as identified by the AS number (with or +without preceding "AS" part). +Filtering by AS number is case-insensitive. +</td></tr> +<tr><td><b>flag</b></td> +<td>Return only relays which have the +given relay flag assigned by the directory authorities. +Note that if the flag parameter is specified more than once, only the +first parameter value will be considered. +Filtering by flag is case-insensitive. +</td></tr> +<tr><td><b>first_seen_days</b></td> +<td>Return only relays or bridges which +have first been seen during the given range of days ago. +A parameter value "x-y" with x >= y returns relays or bridges that have +first been seen at least x and at most y days ago. +Accepted short forms are "x", "x-", and "-y" which are interpreted as +"x-x", "x-infinity", and "0-y". +</td></tr> +<tr><td><b>last_seen_days</b></td> +<td>Return only relays or bridges which +have last been seen during the given range of days ago. +A parameter value "x-y" with x >= y returns relays or bridges that have +last been seen at least x and at most y days ago. +Accepted short forms are "x", "x-", and "-y" which are interpreted as +"x-x", "x-infinity", and "0-y". +Note that relays and bridges that haven't been running in the past week +are never included in results, so that setting x to 8 or higher will +always lead to an empty result set. +</td></tr> +<tr><td><b>contact</b></td><td>Return only relays with the parameter value +matching (part of) the contact line. +If the parameter value contains spaces, only relays are returned which +contain all space-separated parts in their contact line. +Only printable ASCII characters are permitted in the parameter value, +some of which need to be percent-encoded (# as %23, % as %25, & as +%26, + as %2B, and / as %2F). +Comparisons are case-insensitive. +</td></tr> +</table> +<p>Response documents can be reduced in size by requesting only a subset +of contained fields.</p> +<table border="0" cellpadding="4" cellspacing="0" summary=""> +<colgroup> +<col width="150"> +<col width="850"> +</colgroup> +<tr><td><b>fields</b></td><td>Comma-separated list of fields that will be +included in the result. +So far, only top-level fields in relay or bridge objects of details +documents can be specified, e.g., <b>nickname,hashed_fingerprint</b>. +If the fields parameter is provided, all other fields which are not +contained in the provided list will be removed from the result. +Field names are case-insensitive. +</td></tr> +</table> +<p>Relay and/or bridge documents in the response can be ordered and +limited by providing further parameters. +If the same parameter is specified more than once, only the first +parameter value is considered.</p> +<table border="0" cellpadding="4" cellspacing="0" summary=""> +<colgroup> +<col width="150"> +<col width="850"> +</colgroup> +<tr><td><b>order</b></td><td>Re-order results by a comma-separated list +of fields in ascending or descending order. +Results are first ordered by the first list element, then by the second, +and so on. +Possible fields for ordering are: <b>consensus_weight</b>. +Field names are case-insensitive. +Ascending order is the default; descending order is selected by prepending +fields with a minus sign (<b>-</b>). +Relays or bridges which don't have any value for a field to be ordered by +are always appended to the end, regardless or sorting order. +The ordering is defined independent of the requested document type and +does not require the ordering field to be contained in the document. +If no <b>order</b> parameter is given, ordering of results is +undefined. +</td></tr> +<tr><td><b>offset</b></td><td>Skip the given number of relays and/or +bridges. +Relays are skipped first, then bridges. +Non-positive <b>offset</b> values are treated as zero and don't change the +result. +</td></tr> +<tr><td><b>limit</b></td><td>Limit result to the given number of +relays and/or bridges. +Relays are kept first, then bridges. +Non-positive <b>limit</b> values are treated as zero and lead to an empty +result. +When used together with <b>offset</b>, the offsetting step precedes the +limiting step. +</td></tr> +</table> +<br> <a name="summary"></a> <h3><a href="#summary" class="anchor">Summary documents</a></h3> <p>Summary documents contain short summaries of relays with nicknames, @@ -604,189 +787,6 @@ weights documents. Only included for compatibility reasons with the other document types. Required field.</li> </ul> -<br> -<a name="methods"></a> -<h3><a href="#methods" class="anchor">Methods</a></h3> -<p>The following methods each return a single document containing zero or -more relay and/or bridge documents.</p> -<table border="0" cellpadding="4" cellspacing="0" summary=""> -<colgroup> -<col width="150"> -<col width="850"> -</colgroup> -<tr> -<td><b>GET summary</b></td> -<td>Return summaries of all relays and bridges that are currently running -or that have been running in the past week. -</td> -</tr> -<tr> -<td><b>GET details</b></td> -<td>Return details of all relays and bridges that are currently running -or that have been running in the past week. -</td> -</tr> -<tr> -<td><b>GET bandwidth</b></td> -<td>Return bandwidth documents of all relays and bridges that are -currently running or that have been running in the past week. -</td> -</tr> -<tr> -<td><b>GET weights</b></td> -<td>Return weights documents of all relays and bridges that are currently -running or that have been running in the past week. -</td> -</tr> -</table> -<p>Each of the methods above can be parameterized to select only a subset -of relay and/or bridge documents to be included in the response. -If multiple parameters are specified, they are combined using a logical -AND operation, meaning that only the intersection of relays and bridges -matching all parameters is returned. -If the same parameter is specified more than once, only the first -parameter value is considered. -</p> -<table border="0" cellpadding="4" cellspacing="0" summary=""> -<colgroup> -<col width="150"> -<col width="850"> -</colgroup> -<tr><td><b>type</b></td><td>Return only relay (parameter value -<b>relay</b>) or only bridge documents (parameter value -<b>bridge</b>). -Parameter values are case-insensitive. -</td></tr> -<tr><td><b>running</b></td><td>Return only running (parameter value -<b>true</b>) or only non-running relays and/or bridges (paramter value -<b>false</b>). -Parameter values are case-insensitive. -</td></tr> -<tr><td><b>search</b></td><td>Return only relays with the parameter value -matching (part of a) nickname, (possibly $-prefixed) beginning of a -fingerprint, or beginning of an IP address, and bridges with (part of a) -nickname or (possibly $-prefixed) beginning of a hashed fingerprint. -Searches for beginnings of IP addresses are performed on textual -representations of canonical IP address forms, so that searches using CIDR -notation or non-canonical forms will return empty results. -Searches are case-insensitive. -If multiple search terms are given, separated by spaces, the intersection -of all relays and bridges matching all search terms will be returned. -Full fingerprints should always be hashed using SHA-1, regardless of -searching for a relay or a bridge, in order to not accidentally leak -non-hashed bridge fingerprints in the URL. -</td></tr> -<tr><td><b>lookup</b></td><td>Return only the relay with the parameter -value matching the fingerprint or the bridge with the parameter value -matching the hashed fingerprint. -Fingerprints should always be hashed using SHA-1, regardless of looking up -a relay or a bridge, in order to not accidentally leak non-hashed bridge -fingerprints in the URL. -Lookups only work for full fingerprints or hashed fingerprints consisting -of 40 hex characters. -Lookups are case-insensitive. -</td></tr> -<tr><td><b>country</b></td><td>Return only relays which are located in the -given country as identified by a two-letter country code. -Filtering by country code is case-insensitive. -</td></tr> -<tr><td><b>as</b></td> -<td>Return only relays which are located in the -given autonomous system (AS) as identified by the AS number (with or -without preceding "AS" part). -Filtering by AS number is case-insensitive. -</td></tr> -<tr><td><b>flag</b></td> -<td>Return only relays which have the -given relay flag assigned by the directory authorities. -Note that if the flag parameter is specified more than once, only the -first parameter value will be considered. -Filtering by flag is case-insensitive. -</td></tr> -<tr><td><b>first_seen_days</b></td> -<td>Return only relays or bridges which -have first been seen during the given range of days ago. -A parameter value "x-y" with x >= y returns relays or bridges that have -first been seen at least x and at most y days ago. -Accepted short forms are "x", "x-", and "-y" which are interpreted as -"x-x", "x-infinity", and "0-y". -</td></tr> -<tr><td><b>last_seen_days</b></td> -<td>Return only relays or bridges which -have last been seen during the given range of days ago. -A parameter value "x-y" with x >= y returns relays or bridges that have -last been seen at least x and at most y days ago. -Accepted short forms are "x", "x-", and "-y" which are interpreted as -"x-x", "x-infinity", and "0-y". -Note that relays and bridges that haven't been running in the past week -are never included in results, so that setting x to 8 or higher will -always lead to an empty result set. -</td></tr> -<tr><td><b>contact</b></td><td>Return only relays with the parameter value -matching (part of) the contact line. -If the parameter value contains spaces, only relays are returned which -contain all space-separated parts in their contact line. -Only printable ASCII characters are permitted in the parameter value, -some of which need to be percent-encoded (# as %23, % as %25, & as -%26, + as %2B, and / as %2F). -Comparisons are case-insensitive. -</td></tr> -</table> -<p>Response documents can be reduced in size by requesting only a subset -of contained fields.</p> -<table border="0" cellpadding="4" cellspacing="0" summary=""> -<colgroup> -<col width="150"> -<col width="850"> -</colgroup> -<tr><td><b>fields</b></td><td>Comma-separated list of fields that will be -included in the result. -So far, only top-level fields in relay or bridge objects of details -documents can be specified, e.g., <b>nickname,hashed_fingerprint</b>. -If the fields parameter is provided, all other fields which are not -contained in the provided list will be removed from the result. -Field names are case-insensitive. -</td></tr> -</table> -<p>Relay and/or bridge documents in the response can be ordered and -limited by providing further parameters. -If the same parameter is specified more than once, only the first -parameter value is considered.</p> -<table border="0" cellpadding="4" cellspacing="0" summary=""> -<colgroup> -<col width="150"> -<col width="850"> -</colgroup> -<tr><td><b>order</b></td><td>Re-order results by a comma-separated list -of fields in ascending or descending order. -Results are first ordered by the first list element, then by the second, -and so on. -Possible fields for ordering are: <b>consensus_weight</b>. -Field names are case-insensitive. -Ascending order is the default; descending order is selected by prepending -fields with a minus sign (<b>-</b>). -Relays or bridges which don't have any value for a field to be ordered by -are always appended to the end, regardless or sorting order. -The ordering is defined independent of the requested document type and -does not require the ordering field to be contained in the document. -If no <b>order</b> parameter is given, ordering of results is -undefined. -</td></tr> -<tr><td><b>offset</b></td><td>Skip the given number of relays and/or -bridges. -Relays are skipped first, then bridges. -Non-positive <b>offset</b> values are treated as zero and don't change the -result. -</td></tr> -<tr><td><b>limit</b></td><td>Limit result to the given number of -relays and/or bridges. -Relays are kept first, then bridges. -Non-positive <b>limit</b> values are treated as zero and lead to an empty -result. -When used together with <b>offset</b>, the offsetting step precedes the -limiting step. -</td></tr> -</table> </body> </html>