Header Ads Widget

Ticker

6/recent/ticker-posts

Una guía humana para redactar la política de la plataforma API

 

redacción de la política de la plataforma API

Hay algunos idiomas en el mundo que son difíciles de dominar y para el desarrollador de aplicaciones promedio ninguno más que Legaleze , un idioma tan inaccesible que solo unos pocos aprendices pueden hablarlo con fluidez. La dicción y la terminología son generalmente tan difíciles que la mayoría ni siquiera intenta aprender: cuando se les presentan los términos de uso de una API o la política de la plataforma , la mayoría de los desarrolladores simplemente hacen clic en 'Acepto' y continúan con la codificación.

De acuerdo, esta descripción del lenguaje que se encuentra en los documentos legales pretende ser irónica, pero es sorprendente cómo las organizaciones en general esperan que las personas que no son abogados tomen decisiones informadas sobre si pueden aceptar o no términos de uso prolongados Descifrar tales documentos a menudo implica la colaboración entre un abogado y un desarrollador de software, lo cual es menos que ideal dado que hay margen para el error o la mala interpretación cuando uno intenta informar al otro (los abogados que también son especialistas en software son un bien escaso y costoso). Incluso hay sitios web como Términos de servicio; No leí dedicado a evaluar los términos de uso de las principales aplicaciones web para ayudar a los usuarios a combatir lo que TOSDR llama "la mayor mentira en la web". No digerir correctamente la letra pequeña podría hacer que la organización no cumpla con una cláusula en los términos de uso que podría transmitirse directamente a sus clientes.

La aceptación ciega de los términos y condiciones de una API presenta un dilema interesante para cualquiera que ejecute un programa API. Uno podría simplemente tomar una perspectiva emptor de advertencia y no perder el sueño sobre si un consumidor lee la letra pequeña. Sin embargo, también se pueden ver términos y condiciones incomprensibles como una oportunidad perdida: si un cliente existente ignora la letra pequeña, ¿se están desanimando los clientes potenciales? En esta publicación, hemos reunido una guía práctica sobre cómo crear una política de plataforma API , que incluye qué elementos incluir y cómo transmitir la información más vital. Al final del artículo, debería tener una idea de cómo presentar su póliza de manera digerible. de manera que sus clientes realmente lo lean y entiendan, con el objetivo de garantizar que un desarrollador de aplicaciones pueda pasar del descubrimiento al desarrollo lo más rápido posible.

Temas importantes

Casi todos los proveedores de API publican uno o más documentos legales que definen los términos y condiciones bajo los cuales se puede utilizar su API. Estos documentos pueden incluir cualquiera de los siguientes:

  • Condiciones de uso;
  • Política de privacidad;
  • Términos de servicio;
  • Política de cookies (para un portal de desarrolladores).

Documentos legales como estos son comunes en todos los sectores de la tecnología y, en conjunto, definen un contrato entre el proveedor de API y el consumidor, especificando las obligaciones legales de cada uno. Ya sea que firme una hoja de papel o simplemente comience a usar la API, como consumidor está sujeto a este contrato legal. Se podría decir simplemente "por qué molestarse con los contratos", pero esta no es una posición sostenible: la necesidad de definir contratos legales para el uso de una API cubre una miríada de áreas temáticas diferentes, incluida la propiedad intelectual, la protección de datos, la obligación regulatoria y, por supuesto, la comercial acuerdos en los que se paga por el acceso a la API.

Al redactar su propia política de plataforma API, es importante comprender que estos documentos tienden a cubrir varios temas subyacentes clave, a saber:

  • Definición de responsabilidades;
  • Establecer expectativas;
  • Describiendo buen comportamiento.

Dada la realidad de los sistemas legales, es difícil hacer que estos puntos llamen la atención del desarrollador (como Stripe reflexiona sobre sus términos de uso . Sin embargo, es fundamental que estos temas se dibujen para despertar el interés del consumidor de API y asegúrese de que hayan aceptado conscientemente los términos y condiciones a los que se están suscribiendo, o lo hayan llamado la atención del equipo legal de su organización.

Más sobre la política de API: ¿Qué significarán las recientes resoluciones de PSD2 para el acceso a los datos bancarios?

Definición de responsabilidades

Casi todos los documentos legales comienzan con una definición de las responsabilidades de todas las partes involucradas en el contrato y las políticas de la plataforma API no son una excepción. Un contrato legal tradicional contendrá varias oraciones con definiciones prescriptivas de términos como "Usted" y "Nosotros": si es posible, mantenga estos términos en la documentación legal básica, pero resuma los puntos clave con suficiente brevedad para mantener el interés del lector. El nivel de brevedad requerido lo demuestra Instagram , que utiliza una sección numerada de Términos generales para aclarar al consumidor de API lo que es absolutamente necesario saber mientras mantiene los términos de uso más extensos.en el fondo. Es importante “simplificar” los puntos clave de esta manera para resaltar las responsabilidades que tienen el mayor impacto en el consumidor de API. Como hemos visto antes , Instagram persigue activamente eliminar a los consumidores que incumplen sus términos, por lo tanto, expresan su acuerdo en un lenguaje sencillo para garantizar que los consumidores sepan exactamente lo que pueden y no pueden hacer con la API de Instagram.

Estableciendo expectativas

Una vez que se crea un mapa claro de responsabilidades, la política de la plataforma de API debe describir lo que el consumidor de API debe esperar del proveedor de API. Establecer expectativas es sinónimo de un acuerdo de nivel de servicio , pero nuevamente el objetivo debería ser definirlo de tal manera que sea fácil de digerir para el consumidor de API. Esta es casi la parte más importante de la política, ya que el consumidor de API puede necesitar transmitir estas expectativas a sus clientes: si un proveedor de API define la disponibilidad de su API como 99%, por ejemplo, esto se convierte implícitamente en parte de los términos y condiciones entre el consumidor de API y sus clientes.

Sería fácil crear un gran compendio de los aspectos que los proveedores de API deberían tener en cuenta al establecer expectativas, pero una breve lista incluiría:

  • Disponibilidad de la API;
  • Tipos de soporte disponible y su capacidad de respuesta (en términos de alto nivel, no correo electrónico, números de teléfono, etc.);
  • Acceso al portal de desarrolladores, entornos sandbox, actualización de autoridades y derechos (claves de API, ID de cliente de OAuth, etc.);
  • Requisitos para la certificación y la incorporación (selección, controles de cumplimiento, certificación de implementación, etc.)
  • Funcionalidad API como se menciona en la documentación

Ahora que sabemos qué esperar del proveedor de API, el paso final es definir qué se espera del consumidor de API . La siguiente parte describe lo que es un comportamiento aceptable y no aceptable, y comunica las acciones que el proveedor de API podría tomar si no se observan estos buenos comportamientos.

También de este escritor: Revisión del software de administración de API abierta APIMAN de Red Hat

Describiendo buenos comportamientos

Con una imagen clara de las responsabilidades y expectativas, el proveedor de API debe definir cuáles son sus expectativas de "buenos comportamientos" (que pueden estar vinculados a un acuerdo comercial con API de pago ). Los buenos comportamientos se dividen en dos grupos: comportamiento de aplicación y comportamiento del consumidor . Estos grupos tienden a reflejar el interés del desarrollador de la aplicación y del equipo legal, respectivamente.

Comportamiento de la aplicación

El comportamiento de la aplicación se refiere a cómo se codifica un programa de software que consume la API para garantizar que no incumpla sus responsabilidades ni intente superar las expectativas. El comportamiento esperado o forzado en la aplicación se puede manifestar de varias maneras:

  • Aplicación de límites de velocidad para garantizar que las "ráfagas" no excedan un rendimiento determinado en un período definido;
  • Cumplimiento de cuotas con un límite superior en el número de llamadas a la API durante un período determinado;
  • Descartar conexiones HTTP de larga duración o bloquear nuevas conexiones donde se ha infringido un límite superior.

Los consumidores de API deben asegurarse de diseñar e implementar sus aplicaciones para conocer estos buenos comportamientos. Sin hacerlo, corren el riesgo de brindar una mala experiencia de usuario y una disminución de la funcionalidad a los usuarios de su aplicación. Además, si una aplicación infringe repetidamente la política de buen comportamiento, el acceso a la API podría cancelarse por completo.

Comportamiento del consumidor

Si bien el comportamiento de la aplicación se puede codificar, garantizar un buen comportamiento del consumidor de API es un poco más complicado: implica que un ser humano tome una decisión sobre cómo usará una API que puede no coincidir con los términos de uso definidos por el proveedor de API. El comportamiento del consumidor generalmente (pero no siempre) es el resultado de una decisión comercial y no debe ser tomado de forma aislada por un desarrollador de software, sino en conjunto con los equipos legales y comerciales del producto.

La mayoría de los humanos son generalmente subjetivos en sus puntos de vista, por lo que ayuda si los proveedores de API son prescriptivos sobre lo que un consumidor de API puede y no puede hacer con su API con una lista resumida a la manera de Stripe . Los proveedores de API pueden tomarse muy en serio las infracciones de sus términos de uso, como demostró Twitter con el retiro de Politwoops de 9 meses : por lo tanto, es importante que tanto el proveedor como el consumidor sean 100% claros tanto en la definición de comportamiento del consumidor como en el consecuencias de no observarlo.

Reflexiones finales sobre la política de la plataforma

política de plataforma de escala apis nórdicas

Hacer que una política de API sea interesante, relevante y directa es un objetivo que cualquier arquitecto de API o gerente de producto debe tomar en serio. Si bien los abogados siempre tendrán su día para resumir su póliza en jerga, usted debe dar forma activamente al resultado y  asegurarse de que los puntos clave sean fáciles de digerir, comprender y actuar . Si es posible, refleje lo siguiente en su política:

  • Producir un resumen preciso de los puntos clave de los documentos legales, cubriendo responsabilidades, expectativas y comportamientos;
  • Asegúrese de que el resumen esté en un lenguaje de fácil acceso que cualquiera pueda entender (para ver un excelente ejemplo, consulte las Pautas para desarrolladores de Google );
  • Explique claramente las mitigaciones o consecuencias que serán evidentes en caso de incumplimiento de los términos de uso.

Tomar esta acción solo puede mejorar la experiencia del desarrollador , un sello distintivo de las API de calidad a las que puede acceder la comunidad de desarrolladores. A medida que la economía de las API continúa creciendo con una competencia cada vez mayor entre diferentes proveedores de API, este enfoque solo puede, prima facie (como dirían los abogados: smirk :) ayudar a desarrollar una ventaja competitiva para su API en el mercado.

Publicar un comentario

0 Comentarios