Introduction into REST API

Overview

What is REST API? To make it simple, REST API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why REST API can be used practically for any programming language.

Common characteristics of ST Registry REST API resources are as follows:

You access the resource by sending an HTTP request to the ST Registry REST API server. The server replies with a response that contains either the data you requested, or the status indicator, or even both.
All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request). For detailed information regarding status codes please refer to the article HTTP Status codes.

ST Registry REST API specification is based on EPP specification represented in rfc5730, rfc5731, rfc572, rfc5733, in other words its reflect EPP Data model to provide simpler migration for our clients from EPP to REST API in case of needs.

In accordance to the rfc2068 following methods are supported:

  • HEAD – verify resource state
  • GET – read resource
  • POST – update resource
  • PUT – create resource
  • DELETE – delete resource

Currently OPTIONS method is not supported but will be implemented soon. OPTIONS method implementation will not affect API Version number.

REST API require from client to send following headers (all headers are required for each request):

  • Content-Type – identify data format for communication between client and REST API. Currently supported only “application/json”. If provided data format is unknown – API Gateway will return HTTP code 400. I close future ST Registry planning to implement XML data format support for REST API.
  • Api-ClientTransactionId – transaction ID which is totally identified by the client. There is no special requirements for transaction ID.

Optional headers:

  • Api-Version – Identify version of API client would like to communicate with. API Version may affect response format. If version is not defined by client – it will be defined on ST Registry side for each request using latest API Version.

Overal capabilities

ST Registry REST API allows managing a number of features:

  • Manage domains (/domains resource)
  • Manage contact (/contacts resource)
  • Manage hosts (/hosts resource)
  • Manage notifications (/notifications resource)
  • Read client/registrar details (/clients resource)
  • Read client/registrar billing details /billing resource)

Output formats

Currently REST API support response only in JSON format (Content-Type: application/json). In close future we are planning to implement support for XML format.

Request structure

All requests to REST API have the following base URL:

https://apihost/

Where apihost is a host name of ST Registry REST API server. This host name can be acquired by the registrar in their registrar console by visiting page “Profile” -> “Registrar details”. On this page registrar will acquire:

  • Production and sandbox REST API access details
  • Production and sandbox EPP API access details
  • Production and sandbox XMLRPC API access details
  • Sandbox access to the registrar console

Example for REST API Request:

GET https://apihost/contacts/ABC123

Where:

  • https://apihost/ – end point. Host name of ST Registry REST API server.
  • /contacts/ – resource which identify contacts collection
  • /ABC123 – Resource ID which identify contact ID to fetch contact details.