API Dokumentation

Unsere Programmierschnittstelle ist als RESTful Web Service umgesetzt. Für die Authentifizierung muss der API-Schlüssel im Anfrageheader als X-ApiKey übergeben werden. Für den Schreibzugriff muss jedoch das entsprechende Benutzerrecht vom Administrator freigeschaltet werden. Der API-Schlüssel steht in der Benutzerverwaltung zur Verfügung.

Es besteht nur die Möglichkeit Pressemitteilungen, Bilder, Pressemappen und Pressekontakte einzutragen (POST) und diese auszulesen (GET). Es können nur eigene Pressemappen und Pressekontakte ausgelesen werden (Diese Einschränkung gilt nicht für Pressemitteilungen und zugehörige Bilder). Die HTTP-Methoden DELETE und PUT werden im Moment nicht unterstützt.

Der Server antwortet im Datenformat JSON. Wenn eine neue Ressource erstellt wurde, befindet sich ihre URL im Location-Header der Antwort und der Status-Code ist 201 (Created). Wird eine existierende Ressource erfolgreich angefordert, ist der Status-Code 200 (OK). Bei ungültigen Parametern ist der Status-Code 422 (Unprocessable Entity) und der Contentbereich enthält detaillierte Angaben über die Ursache. Eine Übersicht der HTTP Status-Codes ist hier zu finden.

URLs und Parameter

Die URL setzt sich aus der Hostadresse http://www.Businessportal24.com und der URI zusammen.

URI Methode Zweck Parameter und Ausgabe
/service/pressreleases GET Verzeichnis Pressemitteilungen
Name Beschreibung Standardwert Beispielwerte
languages[] Sprachen (als Sprachcode) (alle) de, en
categories[] Kategoriecodes (siehe unten) (alle) 1
limit Anzahl der Ergebnisse limitieren (max. 50) 20
offset Startoffset 0
/service/pressreleases POST Pressemitteilung erstellen
Name Pflichtangabe Beschreibung
press_release[company_id] ja Die ID der Pressemappe
press_release[title] ja Titel
press_release[text] ja Inhalt der Pressemitteilung. Kein HTML möglich, aber Escape-zeichen
press_release[teaser_end] Offset des Zeichens, bei dem der Teaser endet. Startoffset ist 0, Standardwert ist 300
press_release[category_id] ja Kategorie (siehe unten)
press_release[language] ja Sprachcode (siehe unten)
pressrelease[backlink_url] ja Ihr Link zu uns
pressrelease[contacts_list][] IDs der Pressekontakte
/service/pressreleases/1 GET Daten zu einer Pressemitteilung anfordern Beispielausgabe:

{ "id": "1"
, "title": "Hallo Welt"
, "text": "Teaser.\r\n\r\nInhalt der Pressemitteilung...."
, "category_id": "1"
, "teaser_end": "6"
, "language": "de"
, "view_url": "http://www.businessportal24.com/de/hallo-welt.html"
, "company":
    { "view_url": "http://www.businessportal24.com/de/presskit/1/mustermann-gmbh.html"
    , "name": "Mustermann GmbH"
    }
}
/service/pressreleases/1/images GET Verzeichnis Bilder
Name Standardwert Beschreibung Beispielwerte
limit Anzahl der Ergebnisse limitieren (max. 50) 20
offset Startoffset 0
/service/pressreleases/1/images POST Bild erstellen
Name Pflichtangabe Beschreibung
press_release_image[title] ja Titel
press_release_image[description] ja Beschreibung
press_release_image[copyright] ja Urheberrechtliche Angaben
press_release_image[is_preview_image] 1, wenn das Bild für die Vorschau verwendet werden soll, ansonsten 0. 0 ist Standardwert
press_release_image[image] ja Muss als File übergeben werden. Siehe Beispiel
/service/pressreleases/1/images/1 GET Daten zu einem Bild anfordern Beispielausgabe:

{ "id": "1"
, "title": "Pixel"
, "description": "1x1 Pixel"
, "copyright": "creative commons license"
, "image_file_url": "http://www.businessportal24.com/de/primage/download/1"
}
/service/users/me/companies GET Verzeichnis Pressemappen (bzw. Firmen und Agenturen)
Name Standardwert Beschreibung Beispielwerte
limit Anzahl der Ergebnisse limitieren (max. 50) 20
offset Startoffset 0
/service/users/me/companies POST Pressemappe für eine Firma/Agentur erstellen
Name Pflichtangabe Beschreibung
company[name] ja Name der Firma/Agentur
company[address] ja Adresse
company[country_id] ja Länder-ID (siehe unten)
company[phone] ja Telefonnummer
company[fax] Faxnummer
company[email] ja E-Mail Adresse
company[website] ja URL des Internetauftritts
company[logo] Firmenlogo, muss als Datei übergeben werden (siehe Beispiel)
/service/users/me/companies/1 GET Daten zur Pressemappe anfordern
/service/users/me/companies/1/contacts GET Verzeichnis Pressekontakte
Name Standardwert Beschreibung Beispielwerte
limit Anzahl der Ergebnisse limitieren (max. 50) 20
offset Startoffset 0
/service/users/me/companies/1/contacts POST Pressekontakt für eine Pressemappe erstellen
Name Pflichtangabe Beschreibung
contact[salutation_id] ja Anrede: 1 für Herr, 2 für Frau
contact[title] Titel
contact[first_name] ja Vorname
contact[last_name] Nachname
contact[responsibility] Zuständigkeit (Beischreibung als Text)
contact[phone] Telefonnummer
contact[fax] Faxnummer
contact[email] ja E-Mail Adresse
/service/users/me/companies/1/contacts/1 GET Daten zu einem Pressekontakt anfordern

Programmbeispiel

Das folgende Beispiel verwendet PHP mit der Erweiterung pecl_http. Es zeigt, wie man eine Pressemitteilung mit Bild importiert, für die eine eigene Pressemappe und ein eigener Pressekontakt erstellt wird.


<?php

$apiKey = '';
$host = 'http://www.businessportal24.com';
$baseUrl = $host .'/service';


$r = new HttpRequest;
$r->setOptions(array(
  'headers' => array('X-ApiKey' => $apiKey)
));


//Hilfsfunktionen
//------------------------------------------------------

class HttpErrorException extends Exception {}

function processError(HttpRequest $r) {
  $data = json_decode($r->getResponseBody());
  if ($data == null) {
    throw new Exception('invalid server response');
  }

  throw new HttpErrorException(strval($data), $r->getResponseCode());
}

function createResource(HttpRequest $r, $url, $params = null, $files = null) {
  $r->setMethod(HttpRequest::METH_POST);
  $r->setUrl($url);
  if ($params !== null) {
    $r->setPostFields($params);
  }
  if ($files !== null) {
    $r->setPostFiles($files);
  }
  $r->send();

  if ($r->getResponseCode() != 201) {
    processError($r);
  } else {
    return $r->getResponseHeader('Location');
  }
}

function readResource(HttpRequest $r, $url, $params = null) {
  $r->setMethod(HttpRequest::METH_GET);
  $r->setUrl($url);
  $r->setQueryData($params);
  $r->send();

  if ($r->getResponseCode() != 200) {
    processError($r);
  } else {
    $ret = json_decode($r->getResponseBody());
    if ($ret == null) {
      throw new Exception('invalid server-response');
    }
    return $ret;
  }
}

//------------------------------------------------------


//Pressemappe erstellen
$companyUrl = createResource($r, $baseUrl.'/users/me/companies', array(
  'company' => array(
    'name' => 'Mustermann GmbH',
    'address' => 'Musterstr. 42, 4711 Whateverest',
    'country_id' => 177,
    'phone' => '12345',
    'email' => 'Pressekontakt@example.com',
    'website' => 'www.example.com'
  )
));

//Pressemappe einlesen
$company = readResource($r, $companyUrl);

//Pressekontakt erstellen
$contactUrl = createResource($r, $companyUrl.'/contacts', array(
  'contact' => array(
    'salutation_id' => 1,
    'first_name' => 'Max',
    'last_name' => 'Mustermann',
    'phone' => '0815',
    'email' => 'Max.Mustermann@example.com'
  )
));

//Pressekontakt einlesen
$contact = readResource($r, $contactUrl);

//Pressemitteilung erstellen
$pressReleaseUrl = createResource($r, $baseUrl .'/pressreleases', array(
  'press_release' => array(
    'company_id' => $company->id,
    'title' => 'Hallo Welt',
    'text' => "Teaser.\r\n\r\nInhalt der Pressemitteilung....",
    'teaser_end' => 6,
    'backlink_url' => 'http://www.example.com/press-releases/hallo-welt',
    'category_id' => 1,
    'language' => 'de',
    'contacts_list' => array($contact->id)
  )
));

//Bild zur Pressemitteilung hinzufügen
createResource($r, $pressReleaseUrl .'/images',
  array('press_release_image' => array(
    'title' => 'Pixel',
    'description' => '1x1 Pixel',
    'copyright' => 'creative commons license',
    'is_preview_image' => true
  )),
  array('press_release_image' => array(
    'name' => 'image',
    'type' => 'image/gif',
    'file' => dirname(__FILE__).'/pixel.gif'
  ))
);

?>

Hier ein PHP Beispiel, das cURL verwendet.



$apiKey = '';
$host = 'http://www.businessportal24.com';
$baseUrl = $host .'/service';

$r = curl_init();
curl_setopt($r, CURLOPT_HTTPHEADER, array(
  'X-ApiKey: '.  $apiKey
));
curl_setopt($r, CURLOPT_RETURNTRANSFER, true);
curl_setopt($r,CURLINFO_HEADER_OUT,TRUE);


//Hilfsfunktionen
//------------------------------------------------------

class HttpErrorException extends Exception {}

// Quelle: http://stackoverflow.com/questions/3772096/posting-multidimensional-array-with-php-and-curl
function http_build_query_for_curl( $arrays, &$new, $prefix = null ) {

  if ( is_object( $arrays ) ) {
    $arrays = get_object_vars( $arrays );
  }

  foreach ( $arrays AS $key => $value ) {
    $k = isset( $prefix ) ? $prefix . '[' . $key . ']' : $key;
    if ( is_array( $value ) || is_object( $value )  ) {
      http_build_query_for_curl( $value, $new, $k );
    } else {
      $new[$k] = $value;
    }
  }
}


function sendRequest ($r) {
  $resp = curl_exec($r);

  if (curl_errno($r) > 0) {
    throw new Exception('HTTP request failed. cURL error: '. curl_errno($r));
  }
  return $resp;
}

function processError($response, $code) {
  echo $response;
  $data = json_decode($response);
  if ($data == null) {
    throw new Exception("Invalid server response ($code): \r\n". $response);
  }
  throw new HttpErrorException($response, $code);
}

function createResource($r, $url, $params = array()) {
  curl_setopt($r, CURLOPT_POST, true);
  curl_setopt($r, CURLOPT_HTTPGET, false);
  curl_setopt($r, CURLOPT_URL, $url);
  $postData = array();
  http_build_query_for_curl($params, $postData);
  curl_setopt($r, CURLOPT_POSTFIELDS, $postData);
  curl_setopt($r, CURLOPT_HEADER, true);

  $resp = sendRequest($r);

  $respArray = explode("\r\n\r\n", $resp);

  if(curl_getinfo($r, CURLINFO_HTTP_CODE) != 201) {
    processError($resp, curl_getinfo($r, CURLINFO_HTTP_CODE));
  }
  $headers = is_array($respArray) && isset($respArray[count($respArray) - 2])
    ? explode("\r\n", $respArray[count($respArray) - 2])
    : array()
  ;
  foreach ($headers as $header)
  {
    $headerKV = explode(": ", $header);
    if (strtolower($headerKV[0]) == 'location')
    {
      $location = $headerKV[1];
    }
  }

  if (!isset($location))
  {
    throw new Exception('Location header is undefined');
  }
  return $location;
}

function readResource($r, $url) {
  curl_setopt($r, CURLOPT_POST, false);
  curl_setopt($r, CURLOPT_HTTPGET, true);
  curl_setopt($r, CURLOPT_URL, $url);
  curl_setopt($r, CURLOPT_HEADER, false);

  $resp = sendRequest($r);

  if(curl_getinfo($r, CURLINFO_HTTP_CODE) != 200) {
    processError($resp, curl_getinfo($r, CURLINFO_HTTP_CODE));
  } else {
    $ret = json_decode($resp);
    if ($ret == null) {
      throw new Exception('invalid server-response');
    }
    return $ret;
  }
}

//------------------------------------------------------


//Pressemappe erstellen
$companyUrl = createResource($r, $baseUrl.'/users/me/companies', array(
  'company' => array(
    'name' => 'Mustermann GmbH'. uniqid(),
    'address' => 'Musterstr. 42, 4711 Whateverest',
    'country_id' => 177,
    'phone' => '12345',
    'email' => 'Pressekontakt@example.com',
    'website' => 'www.example.com'
  )
));


//Pressemappe einlesen
$company = readResource($r, $companyUrl);

//Pressekontakt erstellen
$contactUrl = createResource($r, $companyUrl.'/contacts', array(
  'contact' => array(
    'salutation_id' => 1,
    'first_name' => 'Max',
    'last_name' => 'Mustermann',
    'phone' => '0815',
    'email' => 'Max.Mustermann@example.com'
  )
));

//Pressekontakt einlesen
$contact = readResource($r, $contactUrl);

//Pressemitteilung erstellen
$pressReleaseUrl = createResource($r, $baseUrl .'/pressreleases', array(
  'press_release' => array(
    'company_id' => $company->id,
    'title' => 'Hallo Welt',
    'text' => "Teaser.\r\n\r\nInhalt der Pressemitteilung....",
    'teaser_end' => 6,
    'backlink_url' => 'http://www.example.com/press-releases/hallo-welt',
    'category_id' => 1,
    'language' => 'de',
    'contacts_list' => array($contact->id)
  )
));

//Bild zur Pressemitteilung hinzufügen
createResource($r, $pressReleaseUrl .'/images',
  array('press_release_image' => array(
    'title' => 'Pixel',
    'description' => '1x1 Pixel',
    'copyright' => 'creative commons license',
    'is_preview_image' => 1,
    'image' => "@". dirname(__FILE__).DIRECTORY_SEPARATOR. 'test.png;type=image/png'
  ))
);

curl_close($r);  

Appendix

Sprachcodes

ID Name
deDeutsch
de_CHDeutsch (Schweiz)
de_ATDeutsch (Österreich)
enEnglisch (UK / USA)
en_IOEnglisch (British Indian Ocean Territory)
en_CAEnglisch (Kanada)
frFranzösisch
fr_MGFranzösisch (Madagaskar)
esSpanisch
es_CLSpanisch (Chile)
itItalienisch
roRomänisch
ptPortugiesisch
pt_BRPortugiesisch (Brasilien)
nlNiederländisch
plPolnisch
trTürkisch
csTschechisch
ruRussisch
ukUkrainisch
zhChinesisch

Kategorien

ID Name
1Handel
2IT
3Finanzen
4Reisen
5Kultur
6Politik
7Medizin
8Sport
9Motor/Verkehr
10Haus
11Mode
12Sonstiges

Länder

ID Name
1Afghanistan
2Netherlands
3Netherlands Antilles
4Albania
5Algeria
6American Samoa
7Andorra
8Angola
9Anguilla
10Antigua and Barbuda
11United Arab Emirates
12Argentina
13Armenia
14Aruba
15Australia
16Azerbaijan
17Bahamas
18Bahrain
19Bangladesh
20Barbados
21Belgium
22Belize
23Benin
24Bermuda
25Bhutan
26Bolivia
27Bosnia and Herzegovina
28Botswana
29Brazil
30United Kingdom
31Virgin Islands, British
32Brunei
33Bulgaria
34Burkina Faso
35Burundi
36Cayman Islands
37Chile
38Cook Islands
39Costa Rica
40Djibouti
41Dominica
42Dominican Republic
43Ecuador
44Egypt
45El Salvador
46Eritrea
47Spain
48South Africa
49Ethiopia
50Falkland Islands
51Fiji Islands
52Philippines
53Faroe Islands
54Gabon
55Gambia
56Georgia
57Ghana
58Gibraltar
59Grenada
60Greenland
61Guadeloupe
62Guam
63Guatemala
64Guinea
65Guinea-Bissau
66Guyana
67Haiti
68Honduras
69Hong Kong
70Svalbard and Jan Mayen
71Indonesia
72India
73Iraq
74Iran
75Ireland
76Iceland
77Israel
78Italy
79East Timor
80Austria
81Jamaica
82Japan
83Yemen
84Jordan
85Christmas Island
86Yugoslavia
87Cambodia
88Cameroon
89Canada
90Cape Verde
91Kazakstan
92Kenya
93Central African Republic
94China
95Kyrgyzstan
96Kiribati
97Colombia
98Comoros
99Congo
100Congo, The Democratic Republic of the
101Cocos (Keeling) Islands
102North Korea
103South Korea
104Greece
105Croatia
106Cuba
107Kuwait
108Cyprus
109Laos
110Latvia
111Lesotho
112Lebanon
113Liberia
114Libyan Arab Jamahiriya
115Liechtenstein
116Lithuania
117Luxembourg
118Western Sahara
119Macao
120Madagascar
121Macedonia
122Malawi
123Maldives
124Malaysia
125Mali
126Malta
127Morocco
128Marshall Islands
129Martinique
130Mauritania
131Mauritius
132Mayotte
133Mexico
134Micronesia, Federated States of
135Moldova
136Monaco
137Mongolia
138Montserrat
139Mozambique
140Myanmar
141Namibia
142Nauru
143Nepal
144Nicaragua
145Niger
146Nigeria
147Niue
148Norfolk Island
149Norway
150Côte d’Ivoire
151Oman
152Pakistan
153Palau
154Panama
155Papua New Guinea
156Paraguay
157Peru
158Pitcairn
159Northern Mariana Islands
160Portugal
161Puerto Rico
162Poland
163Equatorial Guinea
164Qatar
165France
166French Guiana
167French Polynesia
168Réunion
169Romania
170Rwanda
171Sweden
172Saint Helena
173Saint Kitts and Nevis
174Saint Lucia
175Saint Vincent and the Grenadines
176Saint Pierre and Miquelon
177Germany
178Solomon Islands
179Zambia
180Samoa
181San Marino
182Sao Tome and Principe
183Saudi Arabia
184Senegal
185Seychelles
186Sierra Leone
187Singapore
188Slovakia
189Slovenia
190Somalia
191Sri Lanka
192Sudan
193Finland
194Suriname
195Swaziland
196Switzerland
197Syria
198Tajikistan
199Taiwan
200Tanzania
201Denmark
202Thailand
203Togo
204Tokelau
205Tonga
206Trinidad and Tobago
207Chad
208Czech Republic
209Tunisia
210Turkey
211Turkmenistan
212Turks and Caicos Islands
213Tuvalu
214Uganda
215Ukraine
216Hungary
217Uruguay
218New Caledonia
219New Zealand
220Uzbekistan
221Belarus
222Wallis and Futuna
223Vanuatu
224Holy See (Vatican City State)
225Venezuela
226Russian Federation
227Vietnam
228Estonia
229United States
230Virgin Islands, U.S.
231Zimbabwe
232Palestine
233Antarctica
234Bouvet Island
235British Indian Ocean Territory
236South Georgia and the South Sandwich Islands
237Heard Island and McDonald Islands
238French Southern territories
239United States Minor Outlying Islands