<?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="es">

  <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>Compatibilidad hacia atrás en API</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Daniel Mustieles</mal:name>
      <mal:email>daniel.mustieles@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>Javier Mazorra</mal:name>
      <mal:email>mazi.debian@gmail.com</mal:email>
      <mal:years>2016</mal:years>
    </mal:credit>
  </info>

  <title>Estabilidad de la API</title>

  <synopsis>
    <title>Resumen</title>

    <list>
      <item><p>Define las garantías de estabilidad de la API para su proyecto. (<link xref="#stability"/>)</p></item>
      <item><p>Asegúrese de que se cambian los números de versión adecuadamente cuando cambia la API. (<link xref="#versioning"/>)</p></item>
    </list>
  </synopsis>

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

    <p>En un nivel superior, una API (<em>interfaz de programación de aplicaciones</em>) es el límite entre dos componentes cuando se desarrolla contra ellos. Está estrechamente relacionado con una ABI (<em>interfaz binaria de aplicación</em>) que es el límite en tiempo de ejecución. Define las posibles formas en que otros componentes pueden interactuar con un componente. Más concretamente, esto significa que normalmente las cabeceras C de una biblioteca forman su API, y los símbolos compilados de la biblioteca su ABI. La diferencia entre una API y ABI viene dada por la compilación del código: hay ciertas cosas en una cabecera C, como <code>#define</code>, que pueden causar cambiar la API de una biblioteca sin cambiar su ABI. Sin embargo, estas diferencias son en su mayoría académicas, y para todos los propósitos prácticos, la API y ABI se pueden tratar de manera intercambiable.</p>

    <p>Ejemplos de cambios API-incompatibles para una función C serían añadir un nuevo parámetro, cambiar el tipo de retorno de la función, o eliminar un parámetro.</p>

    <p>Sin embargo, muchas otras partes de un proyecto pueden formar una API. Si un demonio se expone en D-Bus, las interfaces exportadas ahí forman una API. Del mismo modo, si una API en C se expone en lenguajes de alto nivel usando GIR, el archivo GIR forma otra API - si cambia, cualquier código de nivel superior que lo utilice también debe cambiar.</p>

    <p>Otros ejemplos de API más inusuales son las ubicaciones del archivo de configuración y sus formatos, y esquemas GSettings. Cualquier cambio en estos podría requerir cambiar el código que usa su biblioteca.</p>
  </section>

  <section id="stability">
    <title>Estabilidad</title>

    <p>La estabilidad de la API se refiere a un cierto nivel de garantía de un proyecto de que su API no cambiará en formas definidas en el futuro, o no cambiarán en absoluto. Generalmente, una API se considera «estable» si se compromete a la compatibilidad con versiones anteriores (definida más abajo); pero las API también podrían comprometerse a ser inestables o incluso compatibles hacia adelante. El propósito de las garantías de estabilidad de la API es permitir a la gente usar su proyecto desde su propio código sin preocuparse de actualizar constantemente su código para mantenerse actualizado con los cambios de la API. Normalmente la garantía de estabilidad de la API significa que el código que se compila contra una versión de una biblioteca funcionará sin problemas contra futuras versiones de esa biblioteca con el mismo número de versión principal — o de manera similar el código que funciona contra un demonio seguirá funcionando contra todas las futuras versiones de ese demonio con el mismo número de versión principal.</p>

    <p>Es posible aplicar distintos niveles de estabilidad de API a los componentes dentro de un proyecto. Por ejemplo, las funciones del núcleo en una biblioteca podrían ser estables, y por lo tanto sus API dejarse sin cambios en el futuro; mientras las más nuevas, funciones menos relacionadas con el núcleo, podrían quedarse inestables y podrían cambiar incontroladamente hasta que se encuentra el diseño adecuado, momento en el que se podrían marcar como estables.</p>

    <p>Varios tipos de estabilidad comúnmente considerados:</p>
    <terms>
      <item>
        <title>Inestable</title>
        <p>La API puede cambiar o eliminarse en el futuro.</p>
      </item>
      <item>
        <title>Compatibilidad hacia atrás</title>
        <p>Solo se permiten los cambios que permiten al código compilado contra la API no modificada continuar ejecutándose contra la API modificada (por ejemplo, no se pueden eliminar funciones).</p>
      </item>
      <item>
        <title>Compatibilidad hacia adelante</title>
        <p>Solo se permiten los cambios que permiten al código compilado contra la API modificada continuar ejecutándose contra la API no modificada (por ejemplo, no se pueden añadir funciones).</p>
      </item>
      <item>
        <title>Totalmente estable</title>
        <p>No se permiten cambios en la API, sólo en la implementación.</p>
      </item>
    </terms>

    <p>Normalmente, los proyecto se comprometen a la compatibilidad hacia atrás cuando dicen que una API es «estable». Muy pocos proyectos se comprometen a una estabilidad total porque eso frenaría casi todo desarrollo posterior del proyecto.</p>
  </section>

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

    <p>Las garantías de estabilidad de la API están fuertemente vinculadas a las versiones del proyecto; ambas versiones del paquete y de libtool. El versionado libtool existe completamente con el propósito de trazar la estabilidad de la ABI, y se explica con detalle en <link href="https://autotools.io/libtool/version.htm">Autotools Mythbuster</link> o <link xref="versionin"/>.</p>

    <p>El versionado de paquete (<em>major.minor.micro</em>) está fuertemente vinculado con la estabilidad de la API: normalmente, el número de la versión principal se incrementa cuando se hacen cambios incompatibles hacia atrás (por ejemplo, cuando se renombran funciones, se cambian parámetros, o se eliminan funciones). El número de versión secundaria se incrementa cuando se hacen cambios incompatibles hacia delante (piro ejemplo, cuando se añade una API pública nueva). El número de la micro versión se incrementa cuando se hacen cambios en el código sin modificar la API. Consulte la <link xref="versioning"/> para más información.</p>

    <p>El versionado de las API es tan importante para las API D-Bus y esquemas GSettings (si es probable que cambien) como para las API C. Vea la <link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">documentación en versionado de la API D-Bus</link> para más detalles.</p>

    <p>Para API GIR, su estabilidad normalmente sigue la estabilidad de la API C,  ya que se generan a partir de la API C. Una dificultad es que adicionalmente su estabilidad depende de la versión gobject-introspection usada al generar el GIR, pero las versiones recientes no han cambiado mucho por lo que no es una preocupación grande.</p>
  </section>

  <section id="external-links">
    <title>Enlaces externos</title>

    <p>El tema de la estabilidad de la API se trata en los siguientes artículos:</p>
    <list>
      <item><p><link href="http://en.wikipedia.org/wiki/Application_programming_interface">Página de la Wikipedia sobre API</link></p></item>
      <item><p><link href="http://en.wikipedia.org/wiki/Application_binary_interface">Página de la Wikipedia sobre ABI</link></p></item>
      <item><p><link href="http://dbus.freedesktop.org/doc/dbus-api-design.html#api-versioning">Versionado de la documentación de la API de D-Bus</link></p></item>
    </list>
  </section>
</page>