¿Cómo debo crear una buena API (web)

Question

Voy a crear una API para una aplicación web y estoy interesado en lo que las personas pueden sugerir como buenas prácticas.

Ya estoy planeando hacer versiones (la versión 1 solo puede controlar ciertos aspectos del sistema, la versión 2 podría controlar más, pero esto puede necesitar un cambio en la forma en que se realiza la autenticación que sería incompatible con la versión 1), y la autenticación será distinta del nombre de usuario/contraseña estándar que las personas usan para iniciar sesión (si alguien utiliza una herramienta maliciosa, no los abrirá a suplantación completa, solo lo que permita la API).

¿Alguien tiene más ideas o ejemplos de sitios con API especialmente buenas que haya utilizado?

Answer 1

Lea el libro RESTful Web Services, que le ofrece una buena visión general de cómo usar REST en la práctica, y póngase en marcha lo suficientemente rápido como para comenzar ahora, con cierta confianza. Esto es más útil que solo mirar una API existente, ya que también analiza las opciones de diseño y las compensaciones.

Answer 2

Utilice REST.

RESTful la arquitectura de servicios web es fácil de implementar y utiliza las fortalezas y la semántica de HTTP para lo que estaban destinadas. Está orientado a recursos, al igual que la web en sí.

Amazon Web Services, Google y muchos otros ofrecen API REST para interactuar con sus productos.

Answer 3

Me gustaría echar un vistazo a las API probadas:

1. YouTube API
2. Twitter API

Hay mucha discusión sobre si estas API son "buenas", pero creo que su éxito se demuestra , y todos son fáciles de usar.

Answer 4

Utilizar REST.

Lea sobre estándares para API, o copie las ideas de uno de los populares.

Tenga cuidado al autenticar usuarios.

Comience muy muy simple.

Cree un sitio que use su API (incluso si no es útil) para verificar que las cosas funcionen. Tal vez podrías construir una versión móvil del sitio o algo que te obligue a utilizar la API con mucha profundidad.

Answer 5

1) Hornee el número de versión directamente en la URL en lugar de pasarlo como parámetro, ya que eso le da total libertad para cambiar la organización de su espacio de nombres API con cada bache de versión.

2) Mantenga sus reglas de reescritura de URL (si las hubiera) lo más sencillas/ajustadas posible (pero no más simples), al tiempo que hace que sus URL sean lo más bellas posible (pero no más).

3) Siempre busque el mejor código de estado HTTP que pueda encontrar para cada respuesta (y no se olvide de 202 y 207, por ejemplo).

4) Implemente la lógica de validación de parámetros fascista y los mensajes de error informativos.

5) Use encabezados de solicitud HTTP cuando corresponda en lugar de parámetros (como Aceptar, por ejemplo, para permitir a los clientes especificar el formato de datos deseado de la respuesta).

6) Organice sus "nombres" de manera que las direcciones URL utilizadas por diferentes clientes se separen cerca de la "raíz" de su árbol de URL (esto hace más fácil aplicar diferentes mecanismos de autenticación para las diferentes audiencias si es necesario , o incluso mapee diferentes porciones de su árbol de URL a diferentes servidores).

7) Si está publicando páginas web normales fuera del mismo dominio que sus API y usa las mismas credenciales de autenticación, solicite un encabezado X-Requerido-Con en sus solicitudes de API para evitar vulnerabilidades de XSRF.