<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="api-stability" xml:lang="de">

  <info>
    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Abwärtskompatibilität in APIs</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Mario Blättermann</mal:name>
      <mal:email>mario.blaettermann@gmail.com</mal:email>
      <mal:years>2016, 2018</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Christian Kirbach</mal:name>
      <mal:email>christian.kirbach@gmail.com</mal:email>
      <mal:years>2016</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Stefan Melmuk</mal:name>
      <mal:email>stefan.melmuk@gmail.com</mal:email>
      <mal:years>2018</mal:years>
    </mal:credit>
  </info>

  <title>API-Stabilität</title>

  <synopsis>
    <title>Zusammenfassung</title>

    <list>
      <item><p>
        Define API stability guarantees for your project.
        (<link xref="#stability"/>)
      </p></item>
      <item><p>Stellen Sie sicher, dass bei API-Änderungen auch die entsprechende Versionsnummer geändert wird. (<link xref="#versioning"/>)</p></item>
    </list>
  </synopsis>

  <section id="api-and-abi">
    <title>API und ABI</title>

    <p>
      At a high level, an API – <em>Application Programming Interface</em> – is
      the boundary between two components when developing against them. It is
      closely related to an ABI – <em>Application Binary Interface</em> – which
      is the boundary at runtime. It defines the possible ways in which other
      components can interact with a component. More concretely, this normally
      means the C headers of a library form its API, and compiled library
      symbols its ABI. The difference between an API and ABI is given by
      compilation of the code: there are certain things in a C header, such as
      <code>#define</code>s, which can cause a library’s API to change without
      changing its ABI. But these differences are mostly academic, and for all
      practical purposes, API and ABI can be treated interchangeably.
    </p>

    <p>Beispiele für API-inkompatible Änderungen einer C-Funktion wären das Hinzufügen eines neuen Parameters, Ändern des Rückgabetyps einer Funktion oder die Entfernung eines Parameters.</p>

    <p>
      However, many other parts of a project can form an API. If a daemon
      exposes itself on D-Bus, the interfaces exported there form an API.
      Similarly, if a C API is exposed in higher level languages by use of
      GIR, the GIR file forms another API — if it changes, any higher level
      code using it must also change.
    </p>

    <p>Andere Beispiele von eher ungewöhnlichen APIs sind Konfigurationsdateiorte und -formate und GSettings-Schemas. Änderungenen an diesen könnten es erforderlich machen, dass sich auch Code ändern muss, der eine Bibliothek verwendet.</p>
  </section>

  <section id="stability">
    <title>Stabilität</title>

    <p>
      API stability refers to some level of guarantee from a project that its
      API will only change in defined ways in the future, or will not change at
      all. Generally, an API is considered ‘stable’ if it commits to
      backwards-compatibility (defined below); but APIs could also commit to
      being unstable or even forwards-compatible. The purpose of API stability
      guarantees is to allow people to use your project from their own code
      without worrying about constantly updating their code to keep up with
      API changes. Typical API stability guarantees mean that code which is
      compiled against one version of a library will run without problems
      against all future versions of that library with the same major version
      number — or similarly that code which runs against a daemon will
      continue to run against all future versions of that daemon with the same
      major version number.
    </p>

    <p>Es ist möglich, verschiedene Ebenen von API-Stabilitätsgarantien auf Komponententen innerhalb eines Projekts anzubringen. Zum Beispiel könnten die Kernfunktionalitäten einer Bibliothek stabil sein und deshalb auch deren API unverändert bleiben, während die neueren, sekundäreren Funktionenen instabil bleiben und sich sehr stark ändern dürfen, solange bis das richtige Design gefunden wurde und sie dann als sicher gekennzeichnet werden könnten.</p>

    <p>Im Allgemeinen werden verschiedene Typen der Stabilität bezeichnet:</p>
    <terms>
      <item>
        <title>Instabil (<em>unstable</em>)</title>
        <p>Die API kann sich ändern oder in der Zukunft geändert werden.</p>
      </item>
      <item>
        <title>Backwards compatible (Abwärtskompatibilität)</title>
        <p>Es sind nur solche Änderungen zulässig, die einem Code, der gegen die unmodifizierte API kompiliert wird, erlauben, auch mit der geänderten API zu laufen (z.B. können keine Funktionen entfernt werden).</p>
      </item>
      <item>
        <title>Forwards compatible (Aufwärtskompatibilität)</title>
        <p>Es sind nur solche Änderungen zulässig, die einem Code, der gegen die modifizierte API kompiliert wird, erlauben, auch mit der vorherigen API zu laufen (z.B. können keine Funktionen hinzugefügt  werden).</p>
      </item>
      <item>
        <title>Gänzlich unveränderlich (<em>totally stable</em>)</title>
        <p>Es sind keine Änderungen an der API erlaubt, nur an deren Implementation.</p>
      </item>
    </terms>

    <p>
      Typically, projects commit to backwards-compatibility when they say an
      API is ‘stable’. Very few projects commit to total stability because it
      would prevent almost all further development of the project.
    </p>
  </section>

  <section id="versioning">
    <title>Versionierung</title>

    <p>API-Stabilitätsgarantien sind eng mit der Versionierung des Projekts verknüpft; das betrifft sowohl die Paket- als auch die Libtool-Versionierung. Letztere dient ausschließlich dem Zweck, die API-Stabilität zu überwachen, sie wird detailliert in <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link> oder <link xref="versioning"/> erklärt.</p>

    <p>Paketversionierung (<em>major.minor.micro</em>) ist eng mit API-Stabilität verknüpft: typischerweise, wird die Hauptversionsnummer (<em>major version number</em>) erhöht, wenn eine Änderung nicht mehr abwärtskompatibel ist (zum Beispiel wenn Funktionen umbenannt, Parameter geändert oder Funktionen entfernt werden). Die Nebenversionsnummer (<em>minor version number</em>) wird erhöht, wenn eine Änderung nicht mehr aufwärtskompatibel ist (zum Beispiel wenn eine neue öffentliche API hinzugefügt wird). Die dritte Versionsnummer (<em>micro version number</em>) wird erhöht, wenn die Code-Änderungen ohne Änderung der API möglich sind. Siehe <link xref="versioning"/> für weitere Informationen.</p>

    <p>API-Versionierung ist genauso wichtig für D-Bus-Schnittstellen und GSettings-Schemas (falls sie sich häufiger ändern) wie für C-Programmierschnittstellen. Siehe die <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Dokumentation der D-Bus-API-Versionierung</link> für Details.</p>

    <p>
      For GIR APIs, their stability typically follows the C API stability, as
      they are generated from the C API. One complexity is that their stability
      additionally depends on the version of gobject-introspection used in
      generating the GIR, but recent versions have not changed much so this is
      not a major concern.
    </p>
  </section>

  <section id="external-links">
    <title>Externe Links</title>

    <p>Das Thema API-Stabilität wird in den folgenden Artikeln behandelt:</p>
    <list>
      <item><p><link href="https://de.wikipedia.org/wiki/Programmierschnittstelle">Wikipedia-Seite zu Programmierschnittstellen</link></p></item>
      <item><p><link href="https://de.wikipedia.org/wiki/Bin%C3%A4rschnittstelle">Wikipedia-Seite zu Binärschnittstellen</link></p></item>
      <item><p><link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Dokumentation zur Versionierung der D-Bus-API</link></p></item>
    </list>
  </section>
</page>
