restful que example entre ejemplo diseño diferencia arquitectura api api-design

que - ¿Cómo defines una API buena o mala?



que es rest (14)

Creo que lo más importante es la legibilidad, es decir, la calidad que hace que la mayor cantidad de programadores tenga sentido de lo que el código está haciendo en la menor cantidad de tiempo posible. Pero juzgar qué parte del software es legible y cuál no es tiene esa calidad humana indescriptible: confusión. Los puntos que mencionas parcialmente logran cristalizarlos. Sin embargo, en su totalidad tiene que seguir siendo un asunto caso por caso y sería realmente difícil establecer reglas universales.

Fondo:

Estoy tomando una clase en mi universidad llamada "Restricciones de software". En las primeras conferencias estábamos aprendiendo a construir buenas API.

Un buen ejemplo que obtenemos de una función de API realmente mala es la public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); Cª#. La función recibe 3 listas de sockets y los destruye haciendo que el usuario tenga que clonar todos los sockets antes de alimentarlos en Select() . También tiene un tiempo de espera (en microsegundos) que es un int, que establece el tiempo máximo que el servidor puede esperar para un socket. Los límites de esto son +/- 35 minutos (porque es un int).

Preguntas:

  1. ¿Cómo defines una API como ''mala''?
  2. ¿Cómo defines una API como ''buena''?

Puntos a considerar:

  • Nombres de funciones que son difíciles de recordar.
  • Parámetros de función que son difíciles de entender.
  • Mala documentación.
  • Todo está tan interconectado que si necesitas cambiar 1 línea de código, necesitarás cambiar cientos de líneas en otros lugares.
  • Funciones que destruyen sus argumentos.
  • Mala escalabilidad debido a la complejidad "oculta".
  • Se requiere del usuario / dev para construir envoltorios alrededor de la API para que pueda ser utilizada.

Creo que una buena API debería permitir anotaciones personalizadas de IO y administración de memoria si es aplicable.

Un ejemplo típico es que tiene su formato de archivo comprimido personalizado para los datos en el disco y una biblioteca de terceros con una API deficiente desea acceder a los datos en el disco y espera una ruta a un archivo donde puede cargar sus datos.

Este enlace tiene algunos puntos buenos: http://gamearchitect.net/2008/09/19/good-middleware/

En el diseño de la API siempre he encontrado esta nota clave muy útil:
Cómo diseñar una buena API y por qué es importante - por Joshua Bloch

Aquí hay un extracto, recomendaría leer todo / ver el video.

II. Principios generales

  • API debería hacer una cosa y hacerlo bien
  • La API debería ser lo más pequeña posible pero no más pequeña
  • La implementación no debería afectar la API
  • Minimice la accesibilidad de todo
  • Names Matter-API es un lenguaje pequeño
  • La documentación es importante
  • Documentar religiosamente
  • Considerar las consecuencias de rendimiento de las decisiones de diseño de API
  • Efectos de API Las decisiones de diseño sobre el rendimiento son reales y permanentes
  • La API debe coexistir pacíficamente con la plataforma

III. Diseño de clase

  • Minimizar la mutabilidad
  • Subclase solo donde tiene sentido
  • Diseño y Documento para Herencia o Prohibido

IV. Método de diseño

  • No haga que el cliente haga cualquier cosa que el módulo pueda hacer
  • No viole el principio del menor asombro
  • Fallo rápido: informe los errores tan pronto como sea posible después de que ocurran
  • Proporcionar acceso programático a todos los datos disponibles en forma de cadena
  • Sobrecarga con cuidado
  • Utilice los parámetros apropiados y los tipos de devolución
  • Utilice el orden constante de parámetros en todos los métodos
  • Evite largas listas de parámetros
  • Evite los valores de devolución que exigen un procesamiento excepcional

No es necesario que lea la documentación para usarla correctamente.

El signo de una impresionante API.

Se han escrito muchos estándares de codificación y documentos más largos e incluso libros (Pautas de diseño del marco) sobre este tema, pero gran parte de esto solo ayuda a un nivel bastante bajo.

También hay una cuestión de gusto. Las API pueden obedecer todas las reglas en cualquier libro de reglas, y aún apestar, debido a la adherencia servil a varias ideologías en boga. Un culpable reciente es la orientación de patrones, donde los patrones de Singleton (poco más que las variables globales inicializadas) y los patrones de fábrica (una forma de parametrizar la construcción, pero a menudo se implementan cuando no se necesitan) se usan en exceso. Últimamente, es más probable que la Inversión de control (IoC) y la explosión asociada en la cantidad de tipos de interfaz pequeños que agregan complejidad conceptual redundante a los diseños.

Los mejores tutores del gusto son la imitación (leer muchos códigos y API, descubrir qué funciona y qué no funciona), experimentar (cometer errores y aprender de ello) y pensar (no solo hacer lo que está de moda por sí mismo, piensa antes de actuar).

Si la API produce un mensaje de error, asegúrese de que el mensaje y los diagnósticos ayudan a un desarrollador a resolver cuál es el problema.

Mi expectativa es que la persona que llama de una API pasa la entrada correcta. Un desarrollador es el consumidor de cualquier mensaje de error producido por la API (no el usuario final), y los mensajes dirigidos al desarrollador ayudan al desarrollador a depurar su programa de llamadas.

Una API es mala cuando está mal documentada .

Una API es buena cuando está bien documentada y sigue un estándar de codificación .

Ahora bien, estos son dos puntos muy simples y también muy difíciles de seguir, esto lo lleva al área de la arquitectura de software. Necesita un buen arquitecto que estructura el sistema y ayuda al marco a seguir sus propias directrices.

Comentando el código, escribir un manual bien explicado para la API es obligatorio.

Una API puede ser buena si tiene una buena documentación que explica cómo usarla. Pero si el código es limpio, bueno y sigue un estándar dentro de sí mismo, no importa si no tiene una documentación decente.

He escrito un poco sobre la estructura de codificación here

Una API incorrecta es aquella que su público objetivo no usa.

Una buena API es aquella que usa su público objetivo para el propósito para el que fue diseñada.

Una gran API es aquella que utilizan tanto los destinatarios como el público para el fin previsto y una audiencia involuntaria por motivos imprevistos por sus diseñadores.

Si Amazon publica su API como SOAP y REST, y la versión REST gana, eso no significa que la API SOAP subyacente fuera mala.

Me imagino que lo mismo será cierto para ti. Puede leer todo lo que quiera sobre el diseño y hacer su mejor esfuerzo, pero se usará la prueba de ácido. Dedique algo de tiempo a crear formas de obtener retroalimentación sobre lo que funciona y lo que no funciona y prepárese para refactorizar según sea necesario para mejorarlo.

Una buena API es aquella que hace que las cosas simples sean simples (la repetición mínima y la curva de aprendizaje para hacer las cosas más comunes) y las cosas complicadas posibles (máxima flexibilidad, la menor cantidad de suposiciones posible). Un API mediocre es aquel que hace bien uno de estos (ya sea increíblemente simple, pero solo si estás tratando de hacer cosas realmente básicas, o terriblemente poderoso, pero con una curva de aprendizaje muy empinada, etc.). Una API horrible es aquella que no hace bien ninguno de estos.

Una buena API le permite al cliente hacer casi todo lo que necesita hacer, pero no requiere que hagan un montón de trabajo ocupado sin sentido. Ejemplos de "trabajo ocupado sin sentido" serían inicializar campos de estructura de datos, llamar a varias rutinas en una secuencia que nunca varía sin un código personalizado real entre ellas, etc.

El signo más seguro de una API incorrecta es si todos sus clientes quieren envolverlo con su propio código auxiliar. Como mínimo, tu API debería haber proporcionado ese código auxiliar. Lo más probable es que debería haber sido diseñado para proporcionar el mayor nivel de abstracción que los clientes están desarrollando por sí mismos todo el tiempo.

Una buena API tiene un modelo semántico cercano a lo que describe.

Por ejemplo, una API para crear y manipular hojas de cálculo de Excel tendría clases como Workbook , Sheet y Cell , con métodos como Cell.SetValue(text) y Workbook.listSheets() .

  • Útil: aborda una necesidad que aún no se ha cumplido (o mejora las existentes)
  • Fácil de explicar: la comprensión básica de lo que hace debe ser fácil de comprender
  • Sigue algún modelo de objeto de algún dominio problemático o mundo real. Utiliza constructos que tienen sentido
  • Uso correcto de llamadas síncronas y asíncronas. (no bloquees para cosas que toman tiempo)
  • Buen comportamiento predeterminado: cuando sea posible, permita la extensibilidad y el ajuste, pero proporcione los valores predeterminados para todo lo que sea necesario para casos simples.
  • Ejemplos de usos y aplicaciones de muestra de trabajo. Esto es probablemente lo más importante de todo.
  • Excelente documentación
  • Coma su propia comida para perros (si corresponde)
  • Manténgalo pequeño o segúrelo para que no sea un gran espacio contaminado. Mantenga los conjuntos de funcionalidades distintos y aislados con pocas o ninguna dependencia.

Hay más, pero ese es un buen comienzo