api-design - restful - web api architecture best practices
¿Cómo debería construir una buena API(web)? (5)
Lea el libro RESTful Web Services , que le brinda una buena visión general de cómo usar REST en la práctica, y puede ponerse al día 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.
Voy a construir 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 una versión (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 la gente usa 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 particularmente buenas que haya usado?
Use REST .
La arquitectura RESTful de servicios web es fácil de implementar y usa las fortalezas y la semántica de HTTP para lo que se pretendía. 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.
Use REST.
Lea sobre los estándares para las API, o copie las ideas de una de las más 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.
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) Implementar la lógica de validación de parámetros fascistas y mensajes de error informativos.
5) Use los 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 forma que las URL utilizadas por las diferentes audiencias de los 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 esas diferentes audiencias si es necesario, o incluso mapa 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.
Echaré un vistazo a las API probadas:
Hay muchas discusiones sobre si estas API son "buenas", pero creo que se demuestra su éxito, y todas son fáciles de usar.