Introduction into REST API
What is REST API? To make it simple, REST API defines a set of functions to which developers can perform requests and receive responses. The interaction is performed via HTTP protocol: resources are accessed through HTTP requests to the ST Registry REST API server, and every response contains either the requested data or an indication of the request status.
An advantage of such an approach is the wide spread of HTTP — clients can be written in any language that is able to issue HTTP requests, without any protocol-specific tooling.
Specification
ST Registry REST API specification is based on the EPP specification represented in RFC 5730, RFC 5731, RFC 5732 and RFC 5733, and reflects the EPP data model.
HTTP methods
The following HTTP methods are supported. Each method has a fixed meaning applied uniformly to every resource:
| Method | Description |
|---|---|
| GET | Read a resource. |
| POST | Update a resource. |
| PUT | Create a resource. |
| DELETE | Delete a resource. |
Request headers
| Header | Description |
|---|---|
| Required | |
| Api-ClientToken | Auth Token obtained from login. Required on every resource except PUT /auth. |
| Content-Type | Identifies the data format of the request. Currently application/json is supported. |
| Recommended | |
| Api-ClientTransactionId | Transaction identifier defined by the client (UUID), used for tracing requests. Echoed back in every response as cltrid. |
| Optional | |
| Api-Version | Specifies the desired API version. If omitted, the latest version is used. |
Overall capabilities
The REST API provides management of the following resources:
| Resource | Description |
|---|---|
| /domains | Manage domains. |
| /contacts | Manage contacts. |
| /hosts | Manage hosts. |
| /notifications | Manage notifications. |
| /billing | Read billing details. |
| /whois | Read public WHOIS details for any .ST domain. |
| /service-status | Read REST API service health. |
Output format
Currently the REST API supports JSON output only. XML support is planned for a future release.
Request structure
All resources are accessed relative to the base URL https://apihost/. A resource identifier is appended to the resource path:
// read contact ABC-123 GET https://apihost/contacts/ABC-123