If you request an endpoint as HTTP GET, you will get back
the documentation of the method.
For example, call http://rest.panthermedia.net/host-info
in your web browser and you will see the documentation for the
request "host-info".
If you like to get the documentation of a specified version,
please include the version like this: http://rest.panthermedia.net/v1.0/host-info
The last supported version will be returned in the response header like: "X-API-Last-Version: 1.1", if a newer version as the called version exists. Future requests should still use the original URI if you don't intent to use the new version, but it is recommended to use the latest version, because deprecated versions could be removed without future announcement, see also HTTP Error 410 Gone.
To execute methods, please request the same endpoint
with HTTP POST and the required
version and parameters in an urlencoded format.
We recommend also to use "Accept-Encoding: gzip, deflate" if your used HTTP Client supports compression.
POST http://rest.panthermedia.net/host-info
Accept-Version: 1.0
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded
api_key=a5e770dadd779347e0fdd4db91ad883d0592aaca031e2c81234f3cb8008fdd1f&access_key=96c35a3d110cf36709968972e38fb8e9879d656f×tamp=Thu,%2026Jul%202012%2014:53:44%20UTC&nonce=Im%20ar%20andomS%20tring&algo=sha1
Or
POST http://rest.panthermedia.net/v1.0/host-info
Accept-Encoding: gzip, deflate
Content-Type: application/x-www-form-urlencoded
api_key=a5e770dadd779347e0fdd4db91ad883d0592aaca031e2c81234f3cb8008fdd1f&access_key=96c35a3d110cf36709968972e38fb8e9879d656f×tamp=Thu,%2026Jul%202012%2014:53:44%20UTC&nonce=Im%20ar%20andomS%20tring&algo=sha1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsp stat="ok">
[xml-payload-here]
</rsp>
Status Code: 200 OK
Cache-Control: no-store, no-cache, max-age=0, must-revalidate,
post-check=0, pre-check=0
Connection: close
Content-Type: text/xml;charset=UTF-8
Date: Wed, 25 Jun 2014 08:19:01 GMT
Expires: Thu, 1 Jan 1970 00:00:00 GMT
Pragma: no-cache
X-API-Version: v1.0
X-API-Last-Version: v1.1
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsp stat="ok">
[xml-payload-here]
</rsp>
Status Code: 200 OK
Cache-Control: no-store, no-cache, max-age=0, must-revalidate,
post-check=0, pre-check=0
Connection: close
Content-Type: application/json
Date: Wed, 25 Jun 2014 08:19:01 GMT
Expires: Thu, 1 Jan 1970 00:00:00 GMT
Pragma: no-cache
X-API-Version: v1.0
X-API-Last-Version: v1.1
{
"stat": "ok",
[json-payload-here]
}
400 Bad request
Date: Fri, 27 Jul 2012 13:45:10 GMT
Server: Apache/2.2.16
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate,
post-check=0, pre-check=0
Pragma: no-cache
Status: 400 Bad request
Connection: close
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 88
Content-Type: text/html
400 Bad request (algorithm not supported, Supported Algos: sha1 -
sha256 - sha512)
401 Unauthorized
Date: Fri, 27 Jul 2012 13:58:28 GMT
Server: Apache/2.2.16
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate,
post-check=0, pre-check=0
Pragma: no-cache
Status: 401 Unauthorized
Connection: close
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsp stat="fail">
<err code="401" msg="access denied">
</err>
</rsp>
Standard response for successful requests.
The request cannot be fulfilled due to bad syntax, as sample missing required parameter or wrong type of parameter.
Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. Your app not grant the permission to access this user resource or the auth token or access token passed was not valid or maybe expired.
The request was a valid request, but the server is refusing because the account have not enough deposit for the called request.
The request was a valid request, but the server is refusing to respond to it. Your app not grant the permission to access this service, maybe the api key or access key passed was not valid or "User-Agent" is missing. It is also possible that the Web Application Firewall blocks you temporary due to many requests.
The requested resource (media) could not be found but may be available again in the future. Subsequent requests by the client are permissible.
Indicates that the resource (media) requested is no longer available and will not be available again. (old deprecated api version there are no longer available).
If you send a request with missing header informations like "User-Agent".
Please use for "User-Agent" a qualified string like
[YourClient] / [YourAppName],
for example:
"RestSharp / 106.6.10.0 / MyStockImageApp"
Or even better would be to pass the referer too, but this is optional.
[YourClient] / [YourAppName] / [RefererUser-Agent],
Example 1:
"RestSharp / 106.6.10.0 / MyStockImageApp / Mozilla/5.0 (compatible; Googlebot / 2.1; + http: //www.google.com/bot.html)"
Example 2:
"RestSharp / 106.6.10.0 / MyStockImageApp / Mozilla/5.0 (Android; Mobile; rv:13.0) Gecko/13.0 Firefox/13.0"
So we can also guarantee that a bot on our side will not break any rate limits.
for example if a valid authentication (token) has expired.
Too many requests in a given amount of time from the same IP address.
User locked by PantherMedia as sample due legal reasons.
The client has sent too many requests in a given amount of time.
The server either does not recognize the request method.
A generic error message, given when no more specific message is suitable, in this case please open a support request on PantherMedia.
This server error response code indicates that the server is not ready to handle the request. Common causes are, that the server is down for maintenance.
If the Retry-After HTTP header is present, it estimated the time for the recovery of the service.
You can try to fetch the request again with the parameter "dont_validate_content=true" and/or open a support request on PantherMedia.
Each method requires the authentication via "api_key" (alias
"consumer_key") to secure incoming requests.
For most requests work HTTP and HTTPS, except the method "request-token" as sample.
This request is only allowed via HTTPS. Due
to privacy reasons, we recommend to send all requests via HTTPS
and use HTTP only for debugging.
To authenticate a request, please pass your "api_key" in
combination with "access_key", "timestamp" and "nonce" String.
function str_random($len = 8, $allowed_charset=null) {
if($allowed_charset
=== null){
$allowed_charset =
'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
}
return
substr(str_shuffle($allowed_charset), 0, $len);
}
$api_secret = 'd779ff347e0ca031e2c';
$timestamp = str_replace('+0000','UTC', gmdate(DATE_RSS));
$api_key =
'a5e770dadd779347e0fdd4db91ad883d0592aaca031e2c81234f3cb8008fdd1f';
$nonce = str_random();
$data = $timestamp.$api_key.$nonce;
$access_key = hash_hmac('sha1', $data, $api_secret);
RAW response, if you use a wrong api key / access key:
403 Forbidden
Date: Tue, 31 Jul 2012 11:42:57 GMT
Server: Apache/2.2.16
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate,
post-check=0, pre-check=0
Pragma: no-cache
Status: 403 Forbidden
Connection: close
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Length: 61
Content-Type: text/html
403 Forbidden (invalid api or access key)
To authenticate a request that needs to get user data, please
pass the App authentication and the authorized "auth_token" in
combination with "access_token", "timestamp" and "nonce" String.
Hashing the "access_token" is similar to hashing an "access_key".
$token_secret = 'MySecret';
$auth_token = '5e770c81234f3cb8008fdd1fdad883d0592aaca031e2';
$data = $timestamp.$auth_token.$nonce;
$access_token = hash_hmac('sha1', $data, $token_secret);
Each "auth_token" is valid for 10 minutes by
default (for fresh new tokens). If
a request requires an authentication (and the token is commited
by the ressource owner) that is valid less than 30 minutes, this
authentication will be extended by 60 additional minutes. If you like, you can increase the validity up
to 90 days - this should be also renewed from time to time by
your App, but for security reasons it is better the token
outdated and the user must commit a new one.
For more info, see token-valid-until.
RAW response, if the "auth_token" of the requested resource
owner is not authorized or expired - in this case your App
should pass the authentication work flow again:
401 Unauthorized
Date: Fri, 27 Jul 2012 13:58:28 GMT
Server: Apache/2.2.16
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate,
post-check=0, pre-check=0
Pragma: no-cache
Status: 401 Unauthorized
Connection: close
Vary: Accept-Encoding
Content-Encoding: gzip
Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rsp stat="fail">
<err code="401" msg="access denied">
</err>
</rsp>
Instead of the default App and User Authentication, you can also
use OAuth 1.0 to authorize a request. This is
more complex, but also more secure.
If you use OAuth 1.0, then the authentication is sent via HTTP
header instead of HTTP parameter.
A base string of the request containing the HTTP method in
combination with the endpoint and all GET/POST parameters
supplemented by the oauth_* parameter will be hashed to a
signature.
OAuth is supported by many standard libraries of modern
programming languages.
Sample OAuth 1.0 RAW request for Consumer Authentication:
POST http://rest.panthermedia.net/host-info
Accept-Version: 1.0
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_version="1.0",oauth_consumer_key="myconsumerkey",oauth_timestamp="1414675641",oauth_nonce="1TyWAxxTB62",oauth_signature_method="HMAC-SHA1",oauth_signature="i86MF7x5bIMeWpca1%2Fm6cGcaors%3D"
POST http://rest.panthermedia.net/host-info
Accept-Version: 1.0
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_version="1.0",oauth_consumer_key="myconsumerkey",oauth_token="mytoken",oauth_timestamp="1414675641",oauth_nonce="1TyWAxxTB62",oauth_signature_method="HMAC-SHA1",oauth_signature="WyGboe%2BiGDYQxVII0iC%2B1s4l%2BDE%3D"