API Documentation: Getting Started

Introduction

To consume the API you need to run a query against an "Endpoint". An Endpoint is the end of a communication channel which you can query with the required or optional parameters, and data. Imagine this as a list of all possible actions that can be performed with an API. An endpoint will process this information and respond with success (or error) code and a response object.

Authentication

This API is provided via Mashape. This means, that every call against it needs to be authenticated using the X-Mashape-Key, which you can obtain for free at the Mashape Marketplace. After registering, login at Mashape, click the link "Applications" at the top of the page and select "Default Application". You can also create a new application, if you want to. Navigate to the Get the Keys Button in the Application view:

Get Keys button on the right

Choose which API Key you want to copy or regenerate:

Regenerate API Keys

Request Formats

You can pass parameters via GET. All API calls require the header X-Mashape-Key, which includes your Mashape application key (see Authentication).

Endpoint Base:

GET https://dl.p.mashape.com

Request Example:

curl --get --include 'https://dl.p.mashape.com/v1/check/user%40domain.tld' \
  -H 'X-Mashape-Key: <your API key>' \
  -H 'Accept: application/json'
// These code snippets use an open-source library. http://unirest.io/java

HttpResponse response = Unirest.get("https://dl.p.mashape.com/v1/check/user%40domain.tld")
.header("X-Mashape-Key", "<your API key>")
.header("Accept", "application/json")
.asJson();
// These code snippets use an open-source library. http://unirest.io/nodejs

unirest.get("https://dl.p.mashape.com/v1/check/user%40domain.tld")
.header("X-Mashape-Key", "<your API key>")
.header("Accept", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});
// These code snippets use an open-source library. http://unirest.io/php

$response = Unirest\Request::get("https://dl.p.mashape.com/v1/check/user%40domain.tld",
  array(
    "X-Mashape-Key" => "<your API key>",
    "Accept" => "application/json"
  )
);
# These code snippets use an open-source library. http://unirest.io/python

response = unirest.get("https://dl.p.mashape.com/v1/check/user%40domain.tld",
  headers={
    "X-Mashape-Key": "<your API key>",
    "Accept": "application/json"
  }
)
// These code snippets use an open-source library. http://unirest.io/objective-c

NSDictionary *headers = @{@"X-Mashape-Key": @"<your API key>", @"Accept": @"application/json"};
UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
  [request setUrl:@"https://dl.p.mashape.com/v1/check/user%40domain.tld"];
  [request setHeaders:headers];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];
# These code snippets use an open-source library. http://unirest.io/ruby

response = Unirest.get "https://dl.p.mashape.com/v1/check/user%40domain.tld",
  headers:{
    "X-Mashape-Key" => "<your API key>",
    "Accept" => "application/json"
  }
// These code snippets use an open-source library. http://unirest.io/net

Task> response = Unirest.get("https://dl.p.mashape.com/v1/check/user%40domain.tld")
.header("X-Mashape-Key", "<your API key>")
.header("Accept", "application/json")
.asJson();

Response Formats

The response is in JSON format, includes these members:

apiVersion
The version of the API that was called.
message
The error message, only available after failed requests
data
Result data, only available after successful requests
status
A code that indicates, if your request was successful or not (see Status Codes).
links
An array/object of API links (current and similar, if available).

Status Codes

Every API call returns a status code which indicates, if a call was successful or not:

Class Message Description
200 Success The request has succeeded. The information returned with the response is dependent on the method used in the request.
400 Bad Request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Unauthorized Missing Mashape application key. See Authentication to learn how to get your API application key.
404 Not Found The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.