REST API Introduction
  • 15 Oct 2021
  • 3 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

REST API Introduction

  • Dark
    Light
  • PDF

Article Summary

The REST API is available to all Enterprise and Professional customers.

The Mozenda REST API allows you to control your agents and data collections without manually accessing the Web Console. The API can be used to run an agent, get data, check a job’s progress, and more. You can use the API to automate Mozenda-related operations within your own application.

An API call is a URL that invokes specific actions and/or retrieves data. The parameters that are included in the API call determine the actions performed, or what data is retrieved.

The API calls return XML containing the status and details of the made API call (like starting a new job, for example).

Sample response:

<?xml version="1.0" encoding="utf-8"?>
<AgentRunResponse
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Result>Success</Result>
	<AgentID>1003</AgentID>
	<JobID>15852</JobID>
	<JobType>WebPageHarvest</JobType>
</AgentRunResponse>


ResponseMeaning
<Result>Success</Result>The job has successfully started for the specified agent.
<AgentID>1003</AgentID>Identifies the agent for which the job was run.
<JobID>15852</JobID>Provides the Job ID for your records, or for use in other API calls, such as Job.Pause or Job.GetAgentProgress.
<JobType>WebPageHarvest</JobType>Identifies the type of job being executed.

Understanding API calls

API calls can do many of the same things that can be done manually through the Web Console, such as running agents, canceling agents, or exporting agents’ data. Each major function of the Web Console has a corresponding API call.
For example, the Agent.Run API call runs a new job for an agent. If we were to use the Mozenda API to run a new job for an agent with an ID of 1009, the API call would look like the following:

https://api.mozenda.com/rest?WebServiceKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX&Service=Mozenda10&Operation=Agent.Run&AgentID=1009

Each piece of information included in the API call is a parameter. Each parameter has a name and a value.

NameValue
WebServiceKeyXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX
ServiceMozenda10
OperationAgent.Run
AgentID1009
https://api.mozenda.com/rest?WebServiceKey=XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX&Service=Mozenda10&Operation=Agent.Run&AgentID=1009

The first portion of the API call is the URL that seeks the Mozenda servers and identifies itself as an API call:

https://api.mozenda.com/rest?

The next portion of the API call is the web service key, which specifies to the Mozenda servers which account the API is accessing and acts as a password to that account:

&WebServiceKey=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX

After the web service key is the parameter identifying the type of API call being made, which is standard to all Mozenda API calls:

&Service=Mozenda10

After the service parameter, the operation parameter is used to specify which API call is being made (i.e., which Mozenda operation is to be carried out):

&Operation=Agent.Run

Finally, the agent ID parameter, which is required by the Agent.Run API call, indicates which agent is to be run:

&AgentID=1009

GET and POST requests

Most of the operations available through the REST API use GET requests. We use a POST request when the operation may require more data than can fit in the URL.
For example, to add data to a collection in bulk, you can use the POST request version of Collection.AddItem. In the Mozenda REST API Documentation, for operations that use POST requests, it will specify the format of the data to be posted under the Request body subsection.

Attention! Requests usage limitations

When the request limit is exceeded, an HTTP error (429) will be returned.
The following limitations that the user will encounter are :

  1. A user is allowed up to 100 calls per minute.
    • Example: If a user makes 20 calls every 10 seconds this will hit the first limitation.
  2. A user is allowed up to 20 calls "in the queue" (i.e. calls that have not yet returned a response).
    • Example: If a user makes all 25 calls at the same time, this will hit the second limitation.
  3. Calls are handled serially - meaning first in, first out.
    • Example: If a user initiates 10 calls, and call number 1 takes 45 seconds to complete, the second call will begin to be handled after 45 seconds.

Postman

To assist our users with using the API, we have created a Postman library with all of the API operations attached. You can access that here.


Was this article helpful?