Howto: Implementation via API

Aus Imperia Support Wiki

API-integrations cause a lot of work with BerlinOnline. Therefore integrations via API require a special clause in your cooperation contract with BerlinOnline, which are reserved for strategic partnerships.

Requirements

The following requirements have to be met:

  • Your API returns XML oder JSON as output (under no circumstances HTML or Javascript).
  • Your API is reachable via HTTPon port 80.
  • Your API has to be always valid:
    • If you supply XML: Your XML must be valid all of the time. This also means keeping to one single character encoding, usually UTF-8. We recommend using XML-schemas for allowing us to validate your XML responses.
    • If you supply JSON: Your JSON must be valid all of the time and it must be in UTF-8 as character encoding.
    • In case of errors there must be a valid and comprehensible answer, e.g. a JSON-API has to supply a JSON-error message.
  • Your API has to be well documented. There has to be a comprehensive API-documentation and a technical contact for questions.
  • Your technical documentation has to be identical to the real functionality of your API.
  • Your API has to be stable in functionality and operation. Changes to your API must be communicated one month prior to any changes to affect our systems. Bigger changes have to be separated from live API behavior by version numbers.
  • Your API hast to be fast and reliable. A slow API may cause cascading errors. A connection to you API must be established in under 3 seconds, a reply has to reach our systems in under 20 seconds. Your API must have an availability of 99% minimum per week.

Important restrictions

  • Your API must work without making us install external scripts of yours (e.g. PHP, Perl, Javascript, Java) on our servers.
  • Your API may not use value-lists which are not accessible via your API. If such value-lists are not obtainable via API, the value-lists may not change more often than once per quarter. Value-lists must be CSV, JSON or XML.

Please note that all of the above requirements have to be met.

Please note

The following details should be considered for your API:

  • Results should be fetchable per page. Similar to MySQL-LIMIT there should be a possibility to "page" trough results. There should also be an information how many results were found even though the API-call returns only a page. The following example may show the Idea: "Item 1-20 of 132 results".
  • Results should be sortable by all relevant fields.

Procedure

  • You supply your API-documentation and URL(s) for your API to us. If we need Partner-IDs please supply these as well.
  • We build an application based on your API. The URL of this application will be given to you to monitor our development.
  • In close cooperation with you the application gets its final touches and will be launched.