forked from w3c/w3c-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
177 lines (151 loc) · 6.22 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
<!DOCTYPE html>
<html>
<meta charset="utf-8">
<title>W3C API Overview</title>
<link rel="stylesheet" type="text/css" href="style/base.css" />
<h1>W3C API Overview</h1>
<section>
<h2 id=introduction>Introduction</h2>
<p>This page describes the resources forming the W3C API. If you have any problems or requests, please submit an <a href="https://github.com/w3c/w3c-api/issues">issue</a>.</p>
<p>
Anyone with a <a href="https://www.w3.org/accounts/request">W3C Account</a> and an <a
href="https://www.w3.org/users/myprofile/apikeys">API key</a> can use W3C API.
</p>
</section>
<section>
<h2 id=schema>Schema</h2>
<p>All API access is over HTTPS, and accessed from the <code>api.w3.org</code> domain. All data is sent and received as JSON.</p>
<p>The details about the different API endpoints are documented at <a href="https://api.w3.org/doc">https://api.w3.org/doc</a>.</p>
<pre>
$ curl -i https://api.w3.org/groups?apikey=xxx
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, s-maxage=900
Date: Mon, 23 Nov 2015 12:10:43 GMT
Last-Modified: Wed, 18 Nov 2015 22:39:10 GMT
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1448284222
Transfer-Encoding: chunked
Accept-Ranges: bytes
{...}
</pre>
<p>All timestamps are returned in ISO 8601 format:</p>
<pre>
YYYY-MM-DDTHH:MM:SSZ
</pre>
<h2 id="apikeys">API Keys</h2>
<h3 id="generate">Generate API Keys</h3>
<p>
To generate API keys, head to your <a href="https://www.w3.org/users/myprofile/apikeys">W3C API keys management
page</a>.
This page can also be reached from your main <a href="http://www.w3.org/users/myprofile">W3C profile page</a>.
</p>
<p>
You can create several keys (five by default, ask <a href="mailto:sysreq@w3.org">W3C Systems Team</a>) to help
maintain multiple applications.<br/>
Each key must have a label, and may <a href="#restrictions">specify a list of domain names allowed to make
requests to the API</a> (more about this below).
</p>
<h3 id="restrictions">Restricting API Keys</h3>
<p>
If API keys are going to be publicly visible (for example in some client-side Javascript code), it is <strong>highly
recommended</strong> to specify allowed domains when creating or editing them.
</p>
<p>
Requests made with such keys will then be authorized <strong>only</strong> if the origin domain (using
<a href="https://www.w3.org/TR/cors/">CORS</a> <a href="https://www.w3.org/TR/cors/#origin-request-header">Origin
header</a>)
matches one of this key's domains.</p>
<p>If the key is not associated with a domain, the <code>Origin</code> header is not mandatory.
</p>
<h3 id="use">Use an API Key</h3>
<p>
To successfully get data from W3C API, you need to include an API key in every request. There are two ways to do
that:
</p>
<ul>
<li>Using the <code>apikey</code> query parameter: <code>https://api.w3.org/groups?apikey=mgug2t7fylcksswc4gcs08s4gooo0ok</code>
</li>
<li>Using the HTTP Authorization header: <code>Authorization: W3C-API
apikey="mgug2t7fylcksswc4gcs08s4gooo0ok"</code></li>
</ul>
<p>Failing to provide a (valid) key, you will get one of the following HTTP errors:</p>
<ul>
<li>401 Missing API key</li>
<li>403 Invalid API key</li>
</ul>
<h3>Rate limiting</h3>
<p>
By default, each key can make up to 5000 requests per hour. <a href="mailto:sysreq@w3.org">W3C Systems team</a>
can increase that limit.
</p>
<p>
You can check the status of a key in response headers after any request:
</p>
<pre>X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4524
X-RateLimit-Reset: 1439472737</pre>
<p>
Alternatively, the <code>/rate_limit</code> endpoint will give the same information in both JSON and headers, without increasing the number of hits.
</p>
<p>
If this limit is reached, you will get a 429 HTTP Error.
</p>
<h2 id=parameters>Parameters</h2>
<p>The W3C API takes optional parameters that can be passed as an HTTP query string parameter.</p>
<p>List of parameters:</p>
<table>
<thead>
<tr>
<td>Name</td>
<td>Value</td>
<td>Purpose</td>
<td>Example</td>
</tr>
</thead>
<tbody>
<tr>
<td><code>embed</code></td>
<td>boolean</td>
<td>By default, resources will be represented by links. On specific routes, the <code>embed</code> parameter allows to additionnaly embed related resources (see the <a href="http://stateless.co/hal_specification.html">HAL model</a> for more details)</td>
<td>https://api.w3.org/groups?embed=1</td>
</tr>
<tr>
<td><code>_doc</code></td>
<td>1</td>
<td>Show the documentation for a specific endpoint</td>
<td>https://api.w3.org/groups?_doc=1</td>
</tr>
<tr>
<td><code>items</code></td>
<td>Integer</td>
<td>Specify how many items should be listed on a page. Default value: 100, max value: 1000</td>
<td>https://api.w3.org/groups?items=10</td>
</tr>
<tr>
<td><code>page</code></td>
<td>Integer</td>
<td>Specify which page should be displayed, Default value: 1</td>
<td>https://api.w3.org/groups?page=2</td>
</tr>
</tbody>
</table>
<h2 id=http_verbs>HTTP verbs</h2>
<p>For now, the W3C API is read-only. Therefore the only HTTP verb we support is <code>GET</code>.</p>
<h2 id=pagination>Pagination</h2>
<p>As mentioned in the <a href="#parameters">parameters section</a>, requests that return multiple items will be paginated to 100 items by default. You can specify further pages with the <code>?page</code> parameter. For some resources, you can also set a custom page size up to 1000 with the <code>?items</code> parameter.</p>
<p>Note that page numbering is 1-based and that omitting the <code>?page</code> parameter will return the first page.</p>
<h2 id=cors>Cross Origin Resource Sharing</h2>
<p>The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the <a href="http://www.w3.org/TR/cors">CORS W3C Recommendation</a>.</p>
<p>Here’s a sample request sent from a browser hitting <code>http://example.com</code>:</p>
<pre>
$ curl -i https://api.w3.org -H "Origin: http://example.com"
HTTP/1.1 200 OK
Server: nginx/1.2.1
Content-Type: application/json
Access-Control-Allow-Origin: http://example.com
Access-Control-Allow-Credentials: true
</pre>
</section>
</html>