¿Cómo debería crear una buena API (web)?

Question

Voy a crear una API para una aplicación web y me interesa saber qué pueden sugerir las personas como buenas prácticas.

Ya estoy planeando hacerlo versionado (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 el la autenticación será distinta del nombre de usuario/contraseña estándar que las personas usan para iniciar sesión (si alguien usa una herramienta maliciosa, no los abrirá a una suplantación completa, solo lo que permita la API).

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

Answer 1

Leer el Servicios web RESTful libro, que le brinda una buena descripción general de cómo usar REST en la práctica y ponerse al día lo suficientemente rápido como para comenzar ahora, con cierta confianza.Esto es más útil que simplemente mirar una API existente, porque también analiza las opciones de diseño y las compensaciones.

Answer 2

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

2) Mantenga sus reglas de reescritura de URL (si las hay) lo más simples/eficientes posible (pero no más simples), mientras hace que sus URL sean lo más hermosas posible (pero nada más).

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

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

5) Utilice 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 "sustantivos" de tal manera que las URL utilizadas por diferentes audiencias de clientes estén separadas cerca de la "raíz" de su árbol de URL (esto hace que sea más fácil aplicar diferentes mecanismos de autenticación para esas diferentes audiencias si es necesario, o incluso mapear diferentes partes de su árbol de URL a diferentes servidores).

7) Si ofrece páginas web normales en el mismo dominio que sus API y utiliza las mismas credenciales de autenticación, solicite un encabezado X-Requested-With en sus solicitudes de API para evitar vulnerabilidades XSRF.

Answer 3

Yo echaría un vistazo a las API probadas:

1. API de YouTube
2. API de Twitter

Hay muchos debates sobre si estas API son "buenas", pero creo que su éxito está demostrado y todas son fáciles de usar.

Answer 4

Usar DESCANSAR.

La arquitectura de servicios web RESTful es fácil de implementar y utiliza las fortalezas y la semántica de HTTP para lo que fueron diseñadas.Está orientado a recursos, al igual que la propia web.

Servicios web de Amazon, Google y muchos otros ofrecen API REST para interactuar con sus productos.

Answer 5

Utilice DESCANSO.

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

Tenga cuidado al autenticar usuarios.

Empieza muy muy sencillo.

Cree un sitio que utilice su API (incluso si no es útil) para comprobar que todo funciona.Quizás podrías crear una versión móvil del sitio o algo que te obligue a utilizar la API con mucha profundidad.