standard restful practices practicas patterns ejemplo buenas best api api-design

restful - rest api routes



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

¿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.

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

Por favor escriba su API de manera consistente:

  1. Nombres consistentes dentro de la API en sí. 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 hay tal cosa como una pequeña excepción 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 puedo implementar, si elige proporcionarlas, deben tener pocas funciones bien definidas 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. Por favor, no te hagas el 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 quiero usar un controlador como

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

Prefiero una enum que pueda investigar:

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

Hombre, podría seguir ... Poder para ese chico de Josh Bloch: las API bien redactadas pueden ser realmente increíbles ... las malas pueden ser realmente dolorosas.

Encontré lo siguiente para valer un reloj Joshua Bloch: cómo diseñar una buena API y por qué es importante

Los ejemplos están en Java, pero aún puedes dibujar paralelos. Ya que no mencionaste una tecnología específica; Supongo que no quieres soluciones de nicho.

Hay una buena presentación sobre este tema de Joshua Bloch. La presentación usa Java pero las ideas son independientes del lenguaje. Otra fuente (pdf) para una descripción general rápida.