API General Introduction

From Openprovider API documentation

Jump to: navigation, search

Contents

Introduction to the Openprovider API

What is an API?

An API, acronym for Application Programming Interface, is a protocol that defines how communication should take place between two parties, in our case between you (your website/system) and Openprovider. This communication is integrated in scripts: no manual actions from your side are required, it is all automated. Using an API, you can build a strong web application that, for example, can integrate domain availability checks on your website or even build a complete domain order form.

If you are already familiar with APIs, you can skip the remainder of this page and directly navigate to the quick start guide and the function reference.

Did you know? The Openprovider control panel is completely built on the API. Do not ask what our API can do: the answer is "everything"!

Pre-requirement: download API.php

This page contains a number of examples in PHP and introduces a PHP class for easier API reference. If you use another programming language, feel free to read further but you might not get all answers you are expecting - just the global ideas.

We start with downloading our PHP class that greatly simplifies working with the API. Download this class API.php here. Once downloaded, store it on your webserver - you will include it in any script that you create to communicate with Openprovider.

If you think you now have enough info and can continue with an example: feel free to move to that example page right away and extend it with your own functionality using our function reference.

The first steps: initializing the API

Now, start a new PHP script. Include the API class and define the API to connect to use the Openprovider API server. For convenience, we define our username and password here:

<?php

  require_once('API.php');
  $api = new OP_API ('https://api.openprovider.eu');

  $username = "";
  $password = "";

Now the API is ready to use! Every command will follow the same simple array-based structure which we introduce in the next section.

Building your first command

Let's first start with a simple domain availability check. Once finished with this step, you can integrate this script in your website and provide your customers a realtime domain check!

Each command starts with creating a new OP_Request object. Do not forget this step, as the results will then be... surprising.

  $request = new OP_Request;

Now we build the array that forms the request itself. It starts with setting the command, then an authentication section and finally the command-specific parameters, in this case just a domain name and extension:

  $request->setCommand('checkDomainRequest')
    ->setAuth(array('username' => $username, 'password' => $password))
    ->setArgs(array(
      'domains' => array(
          array(
            'name' => 'openprovider',
            'extension' => 'nl'
          ),
        )
      )
    );

Once the command has been built, we must send it to Openprovider!

  $reply = $api->setDebug(1)->process($request);

The setDebug parameter enables you to find problems in your commands: empty variables, wrong values, ... It will output both the command and the response XML strings. In a production environment, leave this out. The call will then be

  $reply = $api->process($request);

Interpreting the response

There are three functions that allow you to process the response of Openprovider very easily:

  • getFaultCode() will return a '0' if everything was okay. If not, the error code is returned.
  • getFaultString() allows you to retrieve a more descriptive error
  • getValue() returns the data section of the response, if any

An example of all three functions is the following:

  if ($reply->getFaultCode() != 0) {
    die('Error ['.$reply->getFaultCode().'] occurred: '.$reply->getFaultString());
  }
  else {
    $availability = $reply->getValue();
    $availability = $availability[0]; // in this command, the response can contain multiple statuses
    echo 'Availability status of '.$availability['domain'].' is: '.$availability['status'];
  }

That's it - you just built your first script with the Openprovider API and you can immediately include it on your website and provide your customers with a nice availability check function!

Extending your script(s)

Now you understand the basics of the API, it's time to look further. Our function reference contains an overview of all available commands and their input and output parameters, including examples on how to call such command.

And if you encounter problems or have questions: do not hesitate to contact our support department!

Views
Personal tools