August 2, 2013 by Roman Ožana

Adding a Project with the Testomato API

 Want to learn more about our API? We’ve got you covered.

NOTE: This article is over nine years old, some information may be out of date, for the latest information on the Testomato API please visit http://help.testomato.com

In today’s post we’d like to provide an overview of our newest addition – adding a project using the Testomato REST API.

We’ll go through the following steps:

  • Login
  • Add a Projects
  • Logout

Here’s a quick overview of API and REST before we get started for those of you who are not familiar with the terms.

An application-programming interface (API) is a set of programming instructions and standards used for accessing web-based applications or web tools. APIs are generally released to the public so that other developers can design products powered by the service that application or tool supplies. In simple terms, this just means that applications can talk to each other without the need of a user action or intervention.

Representational State Transfer (REST) is a set of architectural principles used to design web services, which focus on the structure of a system’s resources. REST has emerged over time as a predominant API design model.

Testomato REST API

Our REST API provides simple interface solutions for Testomato functionality. Basically, your application makes an HTTP request and then, parses the JSON formatted response. We use a CURL command line tool in our documentation to perform URL calls.

All API endpoints require authentication from an API key. Every Testomato project has its own unique API key that protects your data against unwanted access. In order to perform requests, you an API key parameter is mandatory.

In order to make requests, we use standard cURL functions. cURL is a library that allows you to make HTTP requests in PHP. It’s designed to allow you to connect and communicate with different online resources from directly within your PHP script.

To learn more about cURL, we suggest taking a look at PHP’s manual on cURL or going through PHPsense.com’s cURL functions tutorial.

To get started, you’ll need to set up some variables. You’ll need your password and user login (the email you use to log into http://testomato.com/. You also have the option to request user agents.

$login = 'example@email.com';
$password = '12345678910';
$agent = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.71 Safari/537.36';

How to login to our API

The following example is what you’ll need to login and find your SESSION_ID.

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://www.testomato.com/api/auth/login');
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_POSTFIELDS, ['login' => $login, 'password' => $password]);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$session_id = json_decode(curl_exec($curl))->session->id;

You’ll receive a valid JSON response from Testomato, which is sent using the POST method. If something goes wrong, you’ll receive the following response: $response->ok = false and $response->error = true

{
    "id": "123",
    "isLoggedIn": true,
    "session": {
        "id": "4as56d4asf46456f654"
    }
}

If everything was POSTed correctly, you’ll receive the following response: $response->isLoggedIn = true  and $response->session->id

Now, you’ll have your SESSION_ID, which is used to set the session ID for the current session. This ID will be needed to make all future requests with the Testomato API.

Add a Projects

Using a standard GET request with an expected URL and optional period parameters makes adding a project simple.

The possible period parameters are:

  • 5 minutes
  • 30 minutes
  • 1 hour
  • 8 hours
  • 1 day
  • 7 days

You’ll send a POST request to the following resource:

$url = sprintf("https://www.testomato.com/api/project/create?%s", http_build_query(['period' => $period]));

$data = json_encode(['urls' => ['https:\/\/example.com'], 'blank' => false]);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_COOKIE, sprintf("PHPSESSID=%s; path=/", $session_id));
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($curl));

Your response should look like this:

{
  "name": "example.com",
  "url": "https:\/\/www.example.com\/",
  "title": "example.cz",
  "created": "2021-12-22T09:54:39+00:00",
  "status": null,
  "period": "5 minutes",
  "timeout": 7,
  "delay": 50,
  "checkDefaultErrors": true,
  "uptimeEnabled": 15,
  "uptimeUrl": "https:\/\/wikidi.cz\/",
  "userAgent": null,
  "apiKey": "123456",
  "userIds": ["1"],
  "payerId": "1",
  "location": "eu",
  "id": "61c2f5df6s5825193a8b4576",
  "originalUrl": "https:\/\/example.com"
}

Well done! If you receive a 200 header response, you’ve successfully added a new project to your user account. Be careful, when you sending multiple URLs at once – Testomato API will send you JSON Lines responses. You have to split those JSONs before processing them. You can found full example in our help.

Logout

You also have the option to logout of your session after you’ve finished.

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://www.testomato.com/api/auth/logout"));
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_USERAGENT, $agent);
curl_setopt($curl, CURLOPT_COOKIE, sprintf("PHPSESSID=%s; path=/", $session_id));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

Visit Testomato Help site for more information about our REST API or read full code how to Add new Project to Testomato.

Is your website available? Testomato can check your website availability every 15 seconds from 10 different locations around the world and will send you an alert if the site is unavailable.

Keep track of the important parts of your website with simple checks that can run every minute. They can check plain words, HTML code, HTTP headers, redirects … and much more. Never miss anything.

Websites break, it happens all time. You'll be the first to know. Testomato has an extensive database of and will let you know if it finds any error on monitored url.