API en desarrollo:equilibrio entre nuevas funciones y compatibilidad con versiones anteriores

Question

Estoy trabajando ahora en un API para desarrolladores Característica de nuestro producto.

Se lanzó la primera versión y actualmente tiene un pequeño número de usuarios.Desde que comencé a desarrollar su segunda versión, algunas partes fueron reelaboradas y otras eliminadas para hacer la API más elegante y clara.

Pero la implementación de la segunda versión puede ser una molestia para los usuarios de la versión anterior.Nuestro departamento de marketing planea mejorar mucho nuestro producto API y agregarle más funciones.

¿Cómo debo construir el sistema para que
1) No estaríamos limitados a la "versión antigua" para agregar nuevas funciones interesantes.
2) Los usuarios actuales de API no estarán insatisfechos debido a la necesidad de reelaborar sus sistemas para cumplir con la API modificada.

¿O deberían probarse los productos API en un entorno limitado durante un período de tiempo bastante largo antes del lanzamiento público, para que no haya modificaciones significativas en la especificación?

Answer 1

Cuando tenga que realizar cambios en el API que ya tiene algunos usuarios, probablemente, la mejor ruta es a despreciar las antiguas llamadas a la API y fomentar el uso de las nuevas llamadas.

La eliminación de la capacidad de las antiguas llamadas a la API, probablemente romper la funcionalidad del código antiguo, por lo que probablemente va a causar algunos desarrolladores el uso de su API "viejo" para convertirse en algo insatisfecho.

Si su lenguaje proporciona maneras de indicar que cierta funcionalidad ya no se utiliza, puede servir como una indicación para los usuarios dejen de usar viejas llamadas a la API y la transición a nuevas llamadas en su lugar. En Java, el href="http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/deprecation/deprecation.html#javadoc_tag" rel="nofollow noreferrer"> @deprecated etiqueta Javadoc puede dar una información en la documentación que una característica ya no se utiliza, o desde el Java 5 anotación @Deprecated se puede utilizar para aumentar las advertencias en tiempo de compilación en las llamadas a funciones API obsoletas.

Además, probablemente sería una buena idea para proporcionar algunos consejos y sugerencias acerca de la migración de la antigua API a la nueva API para animar a la gente a utilizar la nueva forma de interactuar con la API. Tener ejemplos y código de ejemplo sobre qué hacer y qué no hacer, los usuarios de la API sería capaz de escribir código de acuerdo con la nueva forma, se prefiere.

Va a ser difícil cambiar una API pública, pero con un poco de cuidado en la transición del viejo al nuevo, yo creo que la cantidad de dolor infligido a los usuarios de la API puede ser mitigado en cierta medida .

Aquí hay un artículo sobre cómo y cuándo desaprobar API del Sol, lo que podría proporcionar un poco más de información sobre cuándo sería apropiado para despreciar partes del API.

También, gracias a David Schmitt quien añadió que el atributo Obsolete en .NET es similar a la anotación @Deprecated en Java. (Por desgracia, la edición se sobrescribe con mi edición, ya que ambos estaban editando esta respuesta al mismo tiempo.)

Answer 2

Microsoft es bastante famoso por su compatibilidad hacia atrás loco. Una de las cosas que hicieron fue mantener todas las antiguas llamadas obsoletos, y luego añadir otros nuevos que los nuevos programas podrían utilizar para acceder a las funciones mejoradas que no podían trabajar en la antigua API.

No se ha especificado que el lenguaje de programación que utilice, pero ambos .NET y Java tiene un mecanismo para marcar ciertas llamadas a la API como obsoletas. Si la compatibilidad hacia atrás es muy importante para usted, es posible que desee tomar la misma ruta.

Answer 3

Es un equilibrio que tendrá que golpear con su comunidad:

• Mantener las funciones de edad durante eones y que va a terminar con la API de Win32 (30000 pública funciones)?

• Vuelve a escribir la API todo el tiempo, y se puede obtener algo similar a .NET, donde una nueva revisión sale de vez en cuando (1.0, 2.0, 3.0, 3.5 ...) y se rompe programas o introduce existentes nuevas y mejores formas de hacer las interfaces de usuario, etc.)

Si la comunidad es tolerante a los cambios y abierto a la experimentación, se esfuerzan para una API magra, actual y saber que alguna rotura, también conocido como bit rot, resultará. Si, por el contrario, la comunidad tiene un montón de código heredado y no hay recursos o deseo de llevarlo a la última versión, se debe mantener la compatibilidad hacia atrás o la totalidad de sus cosas simplemente no funcionan en la nueva API.

---

Nota a una de las otras respuestas: deprecating API es una forma de uso frecuente de indicar qué funciones están "en el camino", pero siempre y cuando funcionan, muchos desarrolladores usará incluso en el nuevo código porque los son las funciones que se utilizan para. Hay muy pocos desarrolladores iluminados que tienen tanto la conciencia a prestar atención a las advertencias de hecho "obsoletas" y el tiempo para buscar el código para otras instancias de la antigua API y actualizarlos.

Answer 4

La compatibilidad hacia atrás debe ser el valor por defecto. La única razón por la que debe comprometer este principio es cuando la API es de alguna manera insegura, que obliga a los usuarios a cambiar a métodos más seguros.

Answer 5

applicitations idealmente escritas a su API original, continuarán trabajando con la nueva versión.

Una forma de añadir nuevas características al mismo tiempo asegurándose de que las aplicaciones antiguas siguen funcionando es tener dos versiones de una llamada a la API.

Por ejemplo, supongamos que usted tiene actualmente una función Foo que toma 2 parámetros (argumentos) en la API, pero que decida la nueva versión realmente debería tomar 3 parámetros. Mantenga Foo de la manera que es y añadir una nueva función Foo2 que tiene 3 parámetros.

manera que los usuarios puedan seguir código contra la Foo para la compatibilidad hacia atrás o utilizar el nuevo Foo2 función de si requieren las nuevas características.

Esta técnica se ha utilizado comúnmente bu Microsoft para las API de Windows.