Philip Withnall
philip.withnall@collabora.co.uk 2015
Bakåtkompatibilitet i API:er
Anders Jonsson
anders.jonsson@norsjovallen.se 2018

# API-stabilitet

#

        Sammanfattning

          Definiera garantier för API-stabilitet för ditt projekt. ()
          Säkerställ att versionsnummer ändras på lämpligt sätt då API ändras. ()

# API och ABI

At a high level, an API – Application Programming Interface – is the boundary between two components when developing against them. It is closely related to an ABI – Application Binary Interface – 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 `#define`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.

Exempel på API-inkompatibla ändringar till en C-funktion skulle vara att lägga till en ny parameter, ändra funktionens returtyp eller att ta bort en parameter.

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.

Andra exempel på mer ovanliga API:er är platser och format för konfigurationsfiler, och GSettings-scheman. Alla ändringar till dessa kan kräva att kod som använder ditt bibliotek behöver ändras.

# Stabilitet

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.

Det är möjligt att tillämpa olika nivåer av API-stabilitet till komponenter i ett projekt. Till exempel kan de centrala funktionerna i ett bibliotek vara stabila, och därför kan deras API lämnas oförändrat i framtiden; mindre centrala funktioner skulle kunna lämnas instabila och tillåtas att förändras mycket till dess att rätt design hittats, och vid den tidpunkten skulle de kunna markeras att vara stabila.

Flera typer av stabilitet som vanligen tas i beaktande:

## Instabilt

API:t kan ändras eller tas bort i framtiden.

## Bakåtkompatibelt

Endast ändringar som tillåter kod som kompilerats mot det oförändrade API:t att fortsätta köra mot det ändrade API:t tillåts (till exempel kan inte funktioner tas bort).

## Framåtkompatibelt

Endast ändringar som tillåter kod som kompilerats mot det ändrade API:t att köra mot det oförändrade API:t tillåts (till exempel kan inte funktioner läggas till).

## Fullständigt stabilt

Inga ändringar tillåts i API:t, endast i implementationen.

Typiskt binder sig projekt till bakåtkompatibilitet då de säger att ett API är ”stabilt”. Väldigt få projekt binder sig till fullständig stabilitet då det skulle förhindra nästan all vidare utveckling av projektet.

# Versionering

API-stabilitetsgarantier är starkt länkade till projektversionering; både paketversionering och libtool-versionering. Libtool-versionering existerar enbart för syftet att följa ABI-stabilitet, och förklaras i detalj i Autotools Mythbuster eller .

Package versioning (major.minor.micro) is strongly linked to API stability: typically, the major version number is incremented when backwards-incompatible changes are made (for example, when functions are renamed, parameters are changed, or functions are removed). The minor version number is incremented when forwards-incompatible changes are made (for example, when new public API is added). The micro version number is incremented when code changes are made without modifying API. See for more information.

API-versionering är precis lika viktig för D-Bus-API:er och GSettings-scheman (om de kan förväntas ändras) som för C-API:er. Se dokumentationen om versionering för D-Bus-API:er för detaljer.

För GIR-API:er följer stabiliteten typiskt stabiliteten hos C-API:t eftersom de genereras från C-API:t. En komplexitet är att deras stabilitet dessutom beror på versionen av gobject-introspection som använts vid generering av GIR, men senare versioner har inte ändrats mycket, så detta är inget större problem.

# Externa länkar

Ämnet API-stabilitet täcks i följande artiklar:

Wikipedia-sidan om API:er

Wikipedia-sidan om ABI:er

D-Bus API-versionsdokumentation