Справочник API
Публичный REST API, операция за операцией. Страницы собираются из OpenAPI-документа самого API, поэтому поля, примеры и коды ошибок здесь именно те, которые API проверяет и отправляет.
- Базовый URL
https://ecdsa.com/api/v1- Документ OpenAPI 3.1
- https://ecdsa.com/api/v1/openapi.json
Операции
Signatures
ECDSA signature verification and DER ⇄ raw r‖s conversion.
JWT
Decoding JSON Web Tokens and verifying ES256/ES384/ES512 signatures.
Certificates
X.509 certificate and chain decoding with assessments.
Domain health
TLS signature-health grades of public domains. These operations connect to the domain.
Webhooks
Webhook endpoints of the API key's account and test deliveries. These operations need an API key with the webhooks scope; deliveries are signed with ECDSA P-256 (ES256).
Соглашения
Базовый URL и версии
Адрес каждой операции — https://ecdsa.com/api и путь операции после него, например /v1/verify. Версия входит в путь: в рамках v1 в ответах могут только добавляться поля и коды ошибок, поэтому игнорируйте незнакомые поля, а неизвестный код обрабатывайте по его HTTP-статусу.
Аутентификация
Не нужна: все операции работают анонимно. API-ключи будут необязательными: их можно будет передавать как Authorization: Bearer … или в заголовке X-API-Key, и тогда на вызов будет действовать лимит ключа, а не лимит по IP. Ключи появятся вместе с аккаунтами ecdsa.com. Заголовок с ключом в неверном формате не игнорируется: такой запрос отклоняется с кодом unauthorized.
Запросы
Тело POST-запроса — JSON-объект размером не более 100 КБ, глубина вложенности массивов и объектов в нём — не более 64 (JSON-документы внутри строковых полей тоже учитываются). GET-операции получают входные данные из пути.
Заголовки ответа
Какие заголовки отправляет API и где они применяются:
| Заголовок | Что содержит |
|---|---|
| X-Request-Id | Identifier of this request, also quoted in every error body. A caller's own X-Request-Id (1–128 characters of A–Z, a–z, 0–9, '.', '_', ':' and '-') is echoed unless it contains an API key; otherwise one is generated. |
| X-RateLimit-Limit | Requests allowed per window by the limit reported on this response. |
| X-RateLimit-Remaining | Requests left in the current window. |
| X-RateLimit-Reset | Unix time (seconds) at which the current window ends. |
| X-Quota-Limit | Calls made with an API key only: the size of the account's quota that runs out first for this operation — daily or monthly quota units, or daily domain scans. |
| X-Quota-Remaining | Calls made with an API key only: what is left of that quota after this call. |
| X-Quota-Reset | Calls made with an API key only: Unix time (seconds) at which that quota starts over. |
| Retry-After | Seconds to wait before retrying; for quota_exceeded, until the quota starts over. |
| Allow | The methods this path accepts. |
| WWW-Authenticate | The bearer challenge (RFC 6750), e.g. `Bearer realm="ecdsa.com", error="invalid_token"`. |
Ошибки
На неудачный вызов API отвечает статусом 4xx или 5xx и таким JSON-объектом ошибки; все коды перечислены в таблице ошибок.
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| error | object | да | |
| error.code | string | да | Machine-readable error code. Each response lists the codes it can carry; new codes may be added within v1, so treat an unknown code by its HTTP status. |
| error.message | string | да | Human-readable explanation (English). |
| error.requestId | string | нет | The X-Request-Id of this request — quote it when reporting a problem. Sent since v1.1. |
| error.detail | object | нет | Structured context for the error, such as the offending field; omitted when there is none.
|
| error.docs | string | нет | Where the error codes are explained. Sent since v1.1.
|
Лимиты запросов
60 запросов в минуту с одного IP на весь API и ещё 10 в минуту для операций, которые сканируют домен. Ответ 429 содержит заголовок Retry-After.
Закрытые ключи
Никогда их не отправляйте. Запрос, в котором где-либо есть данные закрытого ключа (блок PEM PRIVATE KEY, ключ OpenSSH, SSH2 или PuTTY, JWK с параметром «d»), отклоняется с кодом private_key_rejected раньше любой другой обработки.