Обзор API-интерфейса W3C

Информация о материале: Родительская категория: Прочие; Категория: W3C

Введение.

Ниже описаны ресурсы, формирующие API W3C. Если у вас возникли проблемы или запросы, пожалуйста, отправьте вопрос.

Любой человек, имеющий учетную запись W3C и ключ API, может использовать W3C API.

Схема W3C.

Весь доступ к API осуществляется по протоколу HTTPS и с домена api.w3.org. Все данные отправляются и принимаются в формате JSON.

Подробности о различных конечных точках API описаны на сайте https://api.w3.org/doc.

$ 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
{...}

Все значения времени возвращаются в формате ISO 8601:

YYYY-MM-DDTHH:MM:SSZ

Ключи API W3C.

Создание ключей API W3C.

Чтобы сгенерировать ключи API, перейдите на страницу управления ключами API W3C. На эту страницу также можно попасть со страницы вашего основного профиля W3C.

Вы можете создать несколько ключей. По умолчанию их пять, обратитесь к команде W3C Systems Team для обслуживания нескольких приложений.
Каждый ключ должен иметь метку и может определять список доменных имен, которым разрешено делать запросы к API (подробнее об этом ниже).

Ограничение ключей API W3C.

Если API-ключи будут публично видны (например, в каком-либо клиентском JavaScript-коде), настоятельно рекомендуется указывать разрешенные домены при их создании или редактировании.

Запросы, сделанные с помощью таких ключей, будут авторизованы только в том случае, если домен происхождения запроса (с помощью CORS заголовка Origin) совпадает с одним из доменов этого ключа.

Если ключ не связан с доменом, заголовок Origin не обязателен.

Использование ключа API W3C.

Чтобы успешно получать данные из W3C API, необходимо включать ключ API в каждый запрос. Это можно сделать двумя способами:

Используя параметр запроса apikey:

https://api.w3.org/groups?apikey=mgug2t7fylcksswc4gcs08s4gooo0ok

Используя заголовок авторизации HTTP:
- ```
Authorization: W3C-API apikey="mgug2t7fylcksswc4gcs08s4gooo0ok"
```

Не предоставив (действительный) ключ, вы получите одну из следующих ошибок HTTP:

```
401 Missing API key
```
```
403 Invalid API key
```

Ограничение при использовании ключей API W3C.

По умолчанию каждый ключ может делать до 5000 запросов в час. Команда W3C Systems может увеличить этот лимит.

Вы можете проверить состояние ключа в заголовках ответа после любого запроса:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4524
X-RateLimit-Reset: 1439472737

В качестве альтернативы, запрос /rate_limit предоставит ту же информацию как в JSON, так и в заголовках, без увеличения количества использования.

Если этот лимит будет достигнут, вы получите ошибку 429 HTTP Error.

Параметры API W3C.

API W3C принимает необязательные параметры, которые могут быть переданы в качестве параметра строки запроса HTTP.

Список параметров:

Название	Значение	Назначение	Пример
`embed`	boolean	По умолчанию ресурсы будут представлены ссылками. На определенных маршрутах параметр `embed` позволяет дополнительно встраивать связанные ресурсы (подробнее см. модель HAL).	`http://stateless.co/hal_specification.html`
`_doc`	1	Показать документацию для конкретной конечной точки	`https://api.w3.org/groups?_doc=1`
`items`	Integer	Укажите, сколько элементов должно быть перечислено на странице. Значение по умолчанию: `100`, максимальное значение: `1000`	`https://api.w3.org/groups?items=10`
`page`	Integer	Укажите, какая страница должна отображаться, значение по умолчанию: `1`	`https://api.w3.org/groups?page=2`

HTTP запросы к API W3C.

На данный момент API W3C доступен только для чтения. Поэтому единственный HTTP-запрос, который поддерживается, это GET.

Постраничные ответы на запросы к API W3C.

Как упоминалось в разделе параметров, запросы, возвращающие несколько элементов, по умолчанию будут постранично отображаться до 100 элементов. Вы можете задать дополнительные страницы с помощью параметра ?page. Для некоторых ресурсов вы также можете задать пользовательский размер страницы до 1000 с помощью параметра ?items.

Обратите внимание, что нумерация страниц по умолчанию равна 1 и что при отсутствии параметра ?page будет возвращена первая страница.

Поддержка CORS для AJAX-запросов в API W3C.

API поддерживает Cross Origin Resource Sharing (CORS) для AJAX-запросов любого происхождения. Подробнее можно ознакомиться с рекомендацией CORS W3C.

Вот пример запроса, отправленного из браузера, находящегося по адресу http://example.com:

$ 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

Перевод с английского официальной документации W3C:
https://www.w3.org/api/

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)