Overview

Helpful Links

Introduction

This tutorial will help you to provide OpenSRS functionality to your customers by integrating API commands into your website that can send XML requests to OpenSRS over HTTPS Post. You can also use API commands to run queries or automate tasks you would otherwise perform manually using the OpenSRS reseller Control Panel.

You can leverage the API to allow registrants to view and update their contact details, nameservers, transfer auth codes, domain locking, whois privacy, and username and password settings. Additionally, the API can be used to perform domain availability lookups, provide domain search suggestions and aftermarket domain lookups, as well as process registrations, transfers, and renewals.

Registrants are set up with a profile in which multiple domains can be stored. A profile is defined by a username, password, and one of the domains in the profile.

Purpose

The method of sending commands to OpenSRS using HTTPS Post supports communication between a client process and the OpenSRS system. This document describes how to formulate the XML commands and how to use HTTPS Post to send the XML commands to OpenSRS.

Using this tutorial as a reference, you can use any programming language to write an implementation that supports this communication. If you are writing your own implementation, please refer to the "Design considerations" section.

The process for executing commands consists of formulating the command in XML and sending it to OpenSRS via HTTPS Post. This guide outlines the basic method for creating the XML in a format usable by OpenSRS and includes some language-specific methods.

The protocol assumes that the client process that is requesting an action waits for a result from the server process in response to the requested action. The protocol does not support session tracking.

This tutorial assumes that you are familiar with XML document design and the methods for sending data via HTTPS Post.

HTTPS Post

The OpenSRS server supports SSL encryption and handles XML posts from OpenSRS authorized resellers. The OpenSRS server:

Applies IP address authentication to all HTTPS Post requests.
Authenticates the user by verifying the username and MD5 signature of the XML, signed using the resellers private key (generated in the RWI) in the request header.

Authenticating with the OpenSRS API

To authenticate against the OpenSRS API service, you need your reseller username, and a API key that you can generate from the reseller Control Panel

For the Live environment, the IP that connects to the API service must be added to an acceptance list. In the account settings of the reseller Control Panel, click on API Settings and add your IP to the API access Rules section.

Testing Environment

OpenSRS provides a full test environment to assist with developing and testing API integration. The Horizon test environment duplicates the functionality of the Live environment, and is connected to the test environments of most of the registry platforms. For test availability, please see the TLD reference chart under the column "Available in Test environment."

Transactions on the test environment are not real – in other words, if you register a domain using the test environment, it is registered on the test environment of the registry in question, but the domain does not resolve. Your Horizon account is funded with money to simulate payment for transactions you perform. If you required additional testing funds, please contact reseller Support.

The Test environment API also requires an API key, but unlike the Live environment, it doesn't require you to authorize your IP address.

Connection Information

Live production environment

Server: rr-n1-tor.opensrs.net

Port: 55443

OT&E test environment

Server: horizon.opensrs.net

Port: 55443

MD5 Authentication

The MD5 Signature provides the authentication required by OpenSRS. The process involves two steps:

Obtain an MD5 signature of the XML Content and the API Key.
(The XML and the API Key are concatenated)
Perform another MD5 of the signature from Step 1 with the API Key.

xml = "<?xml ...>"
api_key = "7e119b3719b651628987d6625fe987dcda890"
md5_obj = hashlib.md5()
md5_obj.update((xml + api_key).encode())
signature = md5_obj.hexdigest()

md5_obj = hashlib.md5()
md5_obj.update((signature + api_key).encode())
signature = md5_obj.hexdigest()