AdExchange - How to Exchange Advertisements Between Portals =========================================================== Version: May 18, 2014 The purpose of this document is to specify the AdExchange interface. The interface defines a mechanism for exchanging advertisements between participating portals such as AcrossLETS/Obelio, Ressourcen-Tauschring/Tauschen-ohne-Geld, Route des SEL, za:rt/Cyclos and others. Exchanged advertisements are keyed with an identifier (ID). The identifier is used for managing the advertisement and for contacting the author. For data privacy reasons the authors' name and contact data are not exchanged between the portals. How to send HTTP requests to an advertisement portal server ----------------------------------------------------------- Participating portals exchange information solely via HTTP/HTTPS requests and responses. All HTTP requests to a participating ad portal server have to use POST as the request method. Participating portals need to specify a single URL (or more, in case of a high-availability cluster) through which all types of requests can be sent. For example the Obelio servers accepts POST requests via the following URLs: https://obelio.com/en/dyn (primary site) https://obelio.org/en/dyn (secondary site) The primary site and the secondary site are backing up each other in an active/active fashion. If one of these sites becomes unavailable, the other site can be used for the request with similar results. (End of the Obelio example.) POST requests to the ad portal must use the ISO-8859-1 or windows-1252 character encoding. The internet media type of the POST request's message body should be "application/x-www-form-urlencoded". Encryption is optional with the above URLs. The same functions can be executed by using http instead of https. The HTTP Response ----------------- The ad portal server will answer to the POST requests by sending a ISO-8859-1 encoded HTTP response document. This document will contain a XML object. The MIME type of the XML response is "text/plain" for easy viewing/debugging with a browser. It is planned to change the MIME type to "application/xml" after the initial implementation is stable. In most cases the ad portal will respond vie the following Standard Response: or The length of the error messages must not exceed 999 characters. The length of the warning must not exceed 999 characters. Forbidden Characters -------------------- Value strings in XML response documents must not contain the following characters: '<', '>', '&', 'Euro sign', 'horizontal tab', 'soft hyphen', 'non-braking space', and '"'. These characters need to be HTML-encoded as following: '<' should be encoded as '<' '>' should be encoded as '>' '&' should be encoded as '&' 'Euro sign' should be encoded as '€' 'horizontal tab' should be avoided or should be replaced by a blank; 'soft hyphen' should be encoded as '­' 'non-breaking space' should be encoded as ' ' '"' should be encoded as '"' All other windows-1252 characters, which are not available in ISO-8859-1, should be encoded as the respective HTML character entity reference. Unicode characters, which are not available in the windows-1252 character set, and control characters should be avoided or should be replace by '?'. Make sure that characters are not double-HTML-encoded. For example, if the '&' in '&' were again HTML-encoded it would produce a nasty reading as '&amp;'. Value strings of POST request message bodies should apply the same HTML-encoding as explained above. After the HTML-encoding the POST value strings are then URL-encoded as required by the internet media type "application/x-www-form-urlencoded". For example, the '&' character will first HTML-encode as '&' and then URL-encode as '%25amp;'. Please note that the encoding methods described above provide an effective protection against cross-site scripting and SQL injection (assuming SQL commands are using doublequotes as string delimiters). Value strings should not contain leading or trailing blanks. How to contact an ad author --------------------------- The author of an advertisement originated in a particular portal can be contacted by sending a POST request to this portal. The author will then receive a server-generated email (or other type of message) from this portal. The email will contain all required information so that the author can reply the requester with specifics about his ad or potentially with his contact data. The POST request's message body has to contain the following parameter/value pairs: version="1.0" cmd="contact_author" authentication="Authentication string of the requesting portal" ad_id="ID of the advertisement" email="email address of the requester" selected_method="recompense method selected by the requester" message="message text formulated by the requester" language="two-letter language code specifying the language of the contact request message" The available recompense methods may change over time. They are not part of this specification. Just as examples the following methods are listed: Crossy Ressourcen-Tauschring Außenkonto Tauschheft zart Route des SEL The length of the authentication string must not exceed 99 characters. The length of the advertisement ID must not exceed 19 decimal digits (64-bit signed integer). The advertisement ID must be greater than zero. The length of the email address must not exceed 99 characters. The length of the message text must not exceed 349999 characters. Supported language codes are 'de' for German, 'en' for English, 'it' for Italian, and 'fr' for French. They must be expressed in lower-case letters. Unsupported language codes lead to 'en' as the default value. If no advertisement existed with the given ad_id, the response will contain acknowledgement="no" with the error message E004. The HTTP response document will be the Standard Response. How to import a new advertisement into an ad portal --------------------------------------------------- An advertisement can be imported into an ad portal by sending a POST request to this portal. The POST request's message body has to contain the following parameter/value pairs: version="1.0" cmd="import_ad" authentication="Authentication string of the requesting portal" ad_id="ID of the advertisement" type="type of the advertisement" category="main category of the advertisement" sub_category="sub-category of the advertisement" offered_methods="list of recompense methods offered by the author, separated by commas" heading="headline of the advertisement" description="description of the advertisement" expiration_date="date, when the advertisement will be automatically removed from the the database. Format is: yyyy-mm-dd" language="two-letter language code specifying the language of the ad content" city="the city, where the author lives" The advertisement type is one of the following: offer request information If the advertisement type 'information' is not supported in a particular portal, this type should be interpreted as 'offer'. The length of the category description must not exceed 99 characters. The length of the sub-category description must not exceed 99 characters. The length of the list of offered recompense methods must not exceed 1999 characters. The length of a single recompense method must not exceed 99 characters. The length of the heading must not exceed 99 characters. The length of the description must not exceed 499 characters. If an advertisement with the same ad_id from the same portal existed already in the database, it will be updated with the content of the imported ad. The HTTP response document will be the Standard Response. How to remove a foreign advertisement from an ad portal ------------------------------------------------------- A foreign advertisement (i.e. one, that has been imported from another advertisement portal) can be removed from the database by sending a POST request to an ad portal. The POST request's message body has to contain the following parameter/value pairs: version="1.0" cmd="remove_ad" authentication="Authentication string of the requesting portal" ad_id="ID of the advertisement" If no advertisement existed with the given ad_id, the response will contain acknowledgement="yes" with no warning message. The HTTP response document will be the Standard Response. How to remove all foreign advertisements from an ad portal ---------------------------------------------------------- All foreign advertisement, which have been imported from another advertisement portal, can be removed from the database by sending a POST request to the portal. The POST request's message body has to contain the following parameter/value pairs: version="1.0" cmd="remove_foreign_ads" authentication="Authentication string of the requesting portal" The HTTP response document will be the Standard Response. How to export all native advertisements from an ad portal --------------------------------------------------------- All native advertisements from an ad portal can be exported by sending a POST request to the portal. The POST request's message body has to contain the following parameter/value pairs: version="1.0" cmd="export_native_ads" authentication="Authentication string of the requesting portal" category_language="this will control, in which language the categories will be expressed" The HTTP response document will contains the following XML object: or and so on. The response document should only list advertisements, which are not yet expired or deleted. The category language is either de, en, fr or it. Error Codes and Messages ------------------------ [E001] Ad portal could not be authenticated. [E002] The function could not be executed, because of missing parameter 'xyz'. [E003] An error occurred while sending the contact request. [E004] No advertisement was found in the database with ID 'xyz'. [E005] Unsupported interface version. [E006] The system is down for administrative purposes. Please try at a later time. [E007] Unknown recompense method 'xyz'. [E008] Invalid value found in parameter 'xyz'.