Al crear una API, ¿debo seguir con funciones pequeñas y muchas llamadas, o algunas llamadas y funciones grandes?

25

Tengo una plataforma de rieles que mantengo. Tiene muchas aplicaciones web diferentes creadas sobre él. Sin embargo, ahora un cliente solicita una API para poder mantener a los usuarios en su sitio, pero aprovechar algunas de las tareas automatizadas que tenemos.

La plataforma se utiliza para crear aplicaciones de seguros y permite su compra en línea, además de proporcionar formas de descargar documentación relacionada con su póliza.

Entonces mi pregunta al construir la API es esta:

Cuando tengo que hacer un montón de cosas, como validate, crear una user, user profiley policy, más o menos al mismo tiempo. ¿Debo hacer 4 llamadas API separadas y hacer que el cliente cree 4 llamadas de su lado? ¿O debería tener una llamada que exceptúe muchos parámetros, que valide al cliente y cree las 3 cosas al mismo tiempo, simplificando las cosas para el cliente?

El cliente, en este caso, obtiene toda la información requerida al mismo tiempo, por lo que no es que haya un flujo natural en su aplicación donde se detenga y pueda hacer una llamada API a mi plataforma.

Después de haber estado en el lado del cliente usando muchas API antes, mi objetivo es hacerlo lo más simple posible para el cliente y hacer que solo hagan una llamada. Sin embargo, esto está dando lugar a bastante grande functionsen la API, de la que tampoco soy fanático.

¿Cómo sugieres que aborde esto?

Como nota, no tengo mucha confianza en la capacidad de los clientes para implementar una API complicada de su lado.

Ryan
fuente

Respuestas:

32

¿Qué tal hacer ambas cosas? Tenga una API de " nivel bajo " (por así decirlo) que exponga las funciones del sistema y tenga otra "capa" que exponga los servicios que un cliente podría querer hacer. Esta capa usaría las API de bajo nivel necesarias, pero aún están expuestas si el cliente las quiere.

ACTUALIZACIÓN: Incluir también algunos de los grandes puntos y comentarios hechos por otros.

  1. Considere si el cliente alguna vez necesitará llamar a uno de los métodos API más pequeños, por ejemplo, ¿es factible llamar a createUserProfile sin también llamar a createUser? Si no, entonces no expongas ese método. Gracias NoobsArePeople2

  2. Un punto simple pero excelente. Punto clave con exponer algo en una API: nunca se puede exponer. Exponga el mínimo necesario para funcionar y luego expanda en lugar de exponer todo y ... bueno, entonces es desnudo y hacer cambios puede ser embarazoso e incómodo . Gracias MichaelT

dreza
fuente
10
+1 Iba a decir algo como esto. Otra pregunta que debe hacer: ¿alguna vez haría alguna de estas cosas de forma aislada en el cliente? Por ejemplo, ¿el cliente necesitaría alguna vez llamar createUserProfilesin él también createUser? Si no, entonces no lo expongas.
NoobsArePeople2
44
@ NoobsArePeople2 excelente punto sobre el si no es necesario, entonces no lo exponga
dreza
99
Punto clave con exponer algo en una API: nunca se puede exponer. Exponga el mínimo necesario para funcionar y luego expanda en lugar de exponer todo y ... bueno, entonces es desnudo y hacer cambios puede ser embarazoso e incómodo.
1
@ryanOptini sí, esa es la línea que seguiría. Pero si diseña esas llamadas de manera API, exponerlas en la capa no debería ser un problema.
dreza
1
@ryanOptini Lo que dijo Dreza.
NoobsArePeople2
10

Creo que lo estás mirando de manera incorrecta. No te preocupes por lo grande | llamadas pequeñas o muchas | pocas llamadas

Piense en los objetos de negocio y las acciones que se pueden realizar con | para | contra esos objetos.

Tienes:

  • Los usuarios
  • Políticas
  • Tarifas
  • ...

Por lo tanto, debe crear llamadas API alrededor de esos objetos.

  • Usuario.Crear
  • User.UpdatePassword
  • Política Validar
  • ...

La idea es crear operaciones atómicas o casi atómicas basadas en los objetos comerciales y sus acciones. Esto simplificará el diseño y la codificación: llamadas que hacen lo que debe hacer el objeto comercial que coincide con el modelo mental o las expectativas de los programadores. Cuando los programadores o arquitectos discuten los requisitos con los analistas de negocios, todos pueden usar la misma terminología y flujo general de operaciones.

El problema con las llamadas de tipo todo en uno más grandes es el riesgo de efectos secundarios. Si Policy.Create también genera un usuario y desencadena alguna otra acción, eso rompería las expectativas de los programadores. Del mismo modo, muchas llamadas pequeñas obligan al programador a recordar llamar a A y luego a B y luego a C para realizar una operación comercial "única".

Y cómo nombra las llamadas se basará en lo que admitirán Rails y sus servicios web de soporte.

Para ser más prescriptivo, esto creará algunas llamadas que toman una serie de parámetros y pueden tener múltiples llamadas en el back-end que están ocultas para el cliente. También terminará con algunas llamadas bastante rápidas / simples donde la API es poco más que un contenedor de la rutina subyacente.


fuente
4

Creo que su intuición es correcta: simplifique la API para los consumidores. Hasta cierto punto, esta es la filosofía detrás de los contratos impulsados ​​por el consumidor .

Más específicamente, la API debería exponer casos de uso empresarial adecuados. Considere el dominio comercial en cuestión: ¿existe realmente la necesidad de esas funciones de bajo nivel? ¿Cuál es el inconveniente de encapsularlos? Las funciones grandes en la API no son un problema en sí mismas. Lo que sería un problema es si una función grande secuencia operaciones que pueden necesitar ser particionadas para permitir la intervención del consumidor.

eulerfx
fuente
1
Además, la API simple no necesariamente significa grandes funciones. La función API puede ser simplemente un "orquestador" que llama a algunas funciones internas de la biblioteca, que a su vez llaman a otras funciones, hasta que tenga el nivel correcto de granularidad en su código.
Misko
3

Personalmente, me gustan las API que:

  1. están optimizados de manera que los casos de uso comunes se puedan realizar fácilmente
  2. las llamadas relacionadas con operaciones CRUD están orientadas a lotes o tienen versiones por lotes
  3. permite la reflexión (para que las personas que escriben complementos o enlaces para otros lenguajes informáticos puedan automatizar el proceso)
Paulo Scardine
fuente