Mejores prácticas y pautas para diseñar una API

Question

¿Cuáles son algunas pautas y mejores prácticas que puedo cumplir al diseñar una API? Como mínimo, sé que una API debe ser fácil de usar y flexible. Lamentablemente, esos términos pueden ser bastante subjetivos, por lo que estaba buscando algunas pautas concretas relacionadas con un buen diseño de API.

Answer 1

He encontrado que los siguientes vale la pena mirar Joshua Bloch - How To Design A Good API and Why it Matters

Los ejemplos están en Java, pero aún se pueden trazar paralelismos. Ya que no mencionaste una tecnología específica; Supongo que no quieres soluciones de nicho.

Answer 2

Hay un good presentation sobre este tema de Joshua Bloch. La presentación usa Java pero las ideas son independientes del lenguaje. Another source (pdf) para una visión general rápida.

Answer 3

Creo que su pregunta no recibirá respuesta en este espacio con la cantidad de información que está dando. He puesto varios enlaces desde escribiendo 'diseño de API' en Google, y en la primera página conseguir estos que se ven bastante bien

http://web.archive.org/web/20151229055009/http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://web.archive.org/web/20090520234149/http://chaos.troll.no/~shausman/api-design/api-design.pdf

Answer 4

Este es un enlace de Microsoft: http://msdn.microsoft.com/en-us/library/ms229042.aspx

También existe este libro: marco Directrices de diseño: Convenciones, modismos y Patrones para .NET reutilizables Bibliotecas

Answer 5

Como alguien que tiene que consumir toneladas de APIs ...

por favor escriba su API de una manera consistente:

1. Nomenclatura constante dentro de la API. Use verbos, nombres, palabras clave EXACTAMENTE del mismo estilo.

2. De acuerdo con el entorno de destino, se usará en. Si .NET, consulte las pautas de nombres de Microsoft.

3. conceptos consistentes. Patrón de fábrica? Patrón de constructor? Métodos estáticos? Interfaces? Solo elija uno y quédese con él. DE VERDAD. No existe una excepción small a la regla. Se destacará como un gran pulgar dolorido. Más de 1 excepción? Tu API es cada vez más amateur.

Aquí hay otro: Especificidad.

1. Las clases base que pueda poner en práctica, si usted elige para proporcionar las mismas, debería tener pocos y bien definidas funciones para implementar. No me diga "GetData()" devuelve un "objeto []" y luego espera que lo implemente, descubra por qué tengo que convertirlo en una cadena [] y luego depurar por qué se lo llama 20 veces. Es mucho mejor tener DataPoint [] GetChartData(), string [] GetLabelData(), etc. y déjame elegir cuáles debo implementar.

2. No se haga tonto con los nombres: PostRenderColorWheelModifyHSVBaseHandler. A menudo puede refactorizar cosas súper específicas en un nombre más genérico + parámetros.

3. Los parámetros de cadena son un no-no! Use enumeraciones. No deseo utilizar un controlador como

   PostRenderHandler ("ColorWheel", "HSV", someDelegate);

Yo más bien como una enumeración puedo investigar:

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate); 

hombre, podría seguir ... Poder para ese tipo de Josh Bloch - APIs bien escrito puede ser realmente impresionante ... los malos pueden ser realmente dolorosos.