Differential D5717 Diff 20425 swh/web/templates/api/api.html

Changeset View

Standalone View

swh/web/templates/api/api.html

Show First 20 Lines • Show All 241 Lines • ▼ Show 20 Lines	<div class="swh-api-1-doc">
<pre><code class="shell">curl -i https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2 \| grep ^Link:		<pre><code class="shell">curl -i https://archive.softwareheritage.org/api/1/origin/1/visits/?per_page=2 \| grep ^Link:
Link: </api/1/origin/1/visits/?last_visit=2&per_page=2>; rel="next",</code></pre>		Link: </api/1/origin/1/visits/?last_visit=2&per_page=2>; rel="next",</code></pre>

<h4 id="rate-limiting">Rate limiting</h4>		<h4 id="rate-limiting">Rate limiting</h4>
<p>		<p>
Due to limited resource availability on the back end side, API usage is currently rate limited.		Due to limited resource availability on the back end side, API usage is currently rate limited.
API users can be either anonymous or authenticated. For rate-limiting purposes, anonymous users		API users can be either anonymous or authenticated. For rate-limiting purposes, anonymous users
are identified by their origin IP address; authenticated users identify themselves via user-specific		are identified by their origin IP address; authenticated users identify themselves via user-specific
credentials, like <a href="#authentication">authentication tokens</a>.		credentials, like <a href="#authentication">authentication tokens</a>.<br/>
		A higher rate-limit quota is available by default for authenticated users.
</p>		</p>

<p>		<p>
Three HTTP response fields will inform you about the current state of limits that apply to your		Three HTTP response fields will inform you about the current state of limits that apply to your
current rate limiting bucket:		current rate limiting bucket:
</p>		</p>
<ul>		<ul>
<li>		<li>
<code>X-RateLimit-Limit</code>: maximum number of permitted requests per hour		<code>X-RateLimit-Limit</code>: maximum number of permitted requests per hour
		(<b>120</b> for anonymous users, <b>1200</b> for authenticated users)
</li>		</li>
<li>		<li>
<code>X-RateLimit-Remaining</code>: number of permitted requests remaining before the next		<code>X-RateLimit-Remaining</code>: number of permitted requests remaining before the next
reset		reset
</li>		</li>
<li>		<li>
<code>X-RateLimit-Reset</code>: the time (expressed in <a		<code>X-RateLimit-Reset</code>: the time (expressed in <a
href="https://en.wikipedia.org/wiki/Unix_time">Unix		href="https://en.wikipedia.org/wiki/Unix_time">Unix
time</a> seconds) at which the current rate limiting will expire, resetting to a fresh		time</a> seconds) at which the current rate limiting will expire, resetting to a fresh
<code>X-RateLimit-Limit</code>		<code>X-RateLimit-Limit</code>
</li>		</li>
</ul>		</ul>
<p>Example:</p>		<p>Example:</p>
<pre><code class="shell">curl -i https://archive.softwareheritage.org/api/1/stat/counters/ \| grep ^X-RateLimit		<pre><code class="shell">curl -i https://archive.softwareheritage.org/api/1/stat/counters/ \| grep ^X-RateLimit
X-RateLimit-Limit: 60		X-RateLimit-Limit: 120
X-RateLimit-Remaining: 54		X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1485794532</code></pre>		X-RateLimit-Reset: 1620639052</code></pre>

<h4 id="authentication">Authentication</h4>		<h4 id="authentication">Authentication</h4>
<p>		<p>
It is possible to perform authenticated requests to the Web API through the use of a bearer token		It is possible to perform authenticated requests to the Web API through the use of a bearer token
sent in HTTP Authorization headers.		sent in HTTP Authorization headers.
<br/>		<br/>
To obtain such a token, an account to the		To obtain such a token, an account to the
<a href="{% url 'oidc-login' %}">Software Heritage Authentication service</a> must be created.		<a href="{% url 'oidc-login' %}">Software Heritage Authentication service</a> must be created.
Show All 21 Lines