Facebook, Google, Github, Netflix y algunos otros gigantes tecnológicos han dado la oportunidad a los desarrolladores y productos de consumir sus datos a través de API y se han convertido en una plataforma para ellos. Incluso si no está escribiendo API para otros desarrolladores y productos, es siempre es muy saludable para su aplicación tener API bellamente diseñadas. Hay un largo debate en Internet sobre las mejores formas de diseñar las API, y es uno de los más matizados. No hay lineamientos oficiales definidos para el mismo. La API es una interfaz a través de la cual muchos desarrolladores interactúan con los datos. Una API bien diseñada siempre es muy fácil de usar y facilita mucho la vida del desarrollador. La API es la GUI para los desarrolladores, si es confusa o no detallada, entonces el desarrollador comenzará a buscar alternativas o dejará de usarla. La experiencia de los desarrolladores es la métrica más importante para medir la calidad de las API. La API es como un artista actuando en el escenario, y sus usuarios son la audiencia 1) Terminologías Los siguientes son los términos más importantes relacionados con las API REST es un objeto o representación de algo, que tiene algunos datos asociados y puede haber un conjunto de métodos para operar en él. Por ejemplo, los animales, las escuelas y los empleados son recursos y son las operaciones que se realizarán en estos recursos. El recurso eliminar, agregar y actualizar son un conjunto de recursos, por ejemplo, es la colección de recursos de la . Las colecciones Empresas empresa (Uniform Locator) es una ruta a través de la cual se puede ubicar un y se pueden realizar algunas acciones en él. URL Resource recurso 2) punto final de la API Escribamos algunas API para que tienen algunos para comprender más. es una API que responderá con la lista de empleados. Algunas API más alrededor de una se verán de la siguiente manera: empresas empleados, /getAllEmployees empresa _/addNewEmployee_ _/updateEmployee_ _/deleteEmployee_ _/deleteAllEmployees_ _/promoteEmployee_ _/promoteAllEmployees_ Y habrá toneladas de otros puntos finales de API como estos para diferentes operaciones. Todos ellos contendrán muchas acciones redundantes. Por lo tanto, sería complicado mantener todos estos puntos finales de API cuando aumenta el número de API. **¿Qué está mal?**La URL solo debe contener recursos (sustantivos), no acciones ni verbos. La ruta de la API contiene la acción junto con el nombre del recurso . /addNewEmployee addNew Employee **Entonces, ¿cuál es la forma correcta?** endpoint es un buen ejemplo, que no contiene ninguna acción. Pero la pregunta es cómo le informamos al servidor sobre las acciones que se realizarán en los recursos de , a saber. ya sea para agregar, eliminar o actualizar? /companies companies Aquí es donde los (GET, POST, DELETE, PUT), también llamados verbos, juegan un papel. métodos HTTP El recurso siempre debe estar en en el extremo de la API y si queremos acceder a una instancia del recurso, siempre podemos pasar la identificación en la URL. plural el método path debe obtener la lista de todas las empresas GET /companies el método ruta debe obtener los detalles de la empresa 34 GET /companies/34 método ruta debe eliminar la empresa 34 DELETE /companies/34 En algunos otros casos de uso, si tenemos recursos bajo un recurso, por ejemplo, empleados de una empresa, algunos de los puntos finales de la API de muestra serían: debe obtener la lista de todos los empleados de la empresa 3 GET /companies/3/employees debe obtener los detalles del empleado 45, que pertenece a la empresa 3 GET /companies/3/employees/45 debe eliminar al empleado 45, que pertenece a la empresa 3 DELETE /companies/3/employees/45 debe crear una nueva empresa y devolver los detalles de la nueva empresa creada POST /companies ¿No son las API ahora más precisas y consistentes? 😎 Conclusión: las rutas deben contener la forma plural de recursos y el método HTTP debe definir el tipo de acción que se realizará en el recurso. 3) Métodos HTTP (verbos) HTTP ha definido algunos conjuntos de métodos que indican el tipo de acción que se realizará en los recursos. La URL es una oración, donde los recursos son sustantivos y los métodos HTTP son verbos. Los métodos HTTP importantes son los siguientes: El método solicita datos del recurso y no debería producir ningún efecto secundario. Por ejemplo devuelve la lista de todos los empleados de la empresa 3. GET /companies/3/employees El método solicita al servidor que un recurso en la base de datos, principalmente cuando se envía un formulario web. Por ejemplo crea un nuevo empleado de la empresa 3. no es , lo que significa que múltiples solicitudes tendrán diferentes efectos. POST cree /companies/3/employees POST idempotente El método solicita al servidor que el recurso o el recurso, si no existe. Por ejemplo solicitará al servidor que actualice o cree, si no existe, el recurso en la colección de empleados bajo la compañía 3. es , lo que significa que varias solicitudes tendrán los mismos efectos. PUT actualice cree /companies/3/employees/john john PUT idempotente El método solicita que los recursos, o su instancia, se eliminen de la base de datos. Por ejemplo, solicitará al servidor que elimine el recurso de la colección de empleados en la empresa 3. DELETE /companies/3/employees/john/ john Hay que discutiremos en otra publicación. algunos otros métodos 4) Códigos de estado de respuesta HTTP Cuando el cliente envía una solicitud al servidor a través de una API, el cliente debe conocer los comentarios, si falló, pasó o si la solicitud fue incorrecta. Los códigos de estado HTTP son un montón de códigos estandarizados que tienen varias explicaciones en varios escenarios. El servidor siempre debe devolver el código de estado correcto. Las siguientes son las categorizaciones importantes de los códigos HTTP: 2xx (categoría de éxito) Estos códigos de estado representan que el servidor recibió y procesó correctamente la acción solicitada. La respuesta HTTP estándar que representa el éxito de GET, PUT o POST. 200 Ok Este código de estado debe devolverse cada vez que se crea la nueva instancia. Por ejemplo, al crear una nueva instancia, utilizando el método POST, siempre debe devolver el código de estado 201. 201 Creado representa que la solicitud se procesó con éxito, pero no ha devuelto ningún contenido. ELIMINAR puede ser un buen ejemplo de esto. La API eliminará el empleado 2 y, a cambio, no necesitamos ningún datos en el cuerpo de respuesta de la API, ya que le pedimos explícitamente al sistema que los elimine. Si hay algún error, como si no existe en la base de datos, entonces el código de respuesta no sería de la sino de la . 204 Sin contenido DELETE /companies/43/employees/2 employee 2 2xx Success Category 4xx Client Error category 3xx (categoría de redirección) indica que el cliente ya tiene la respuesta en su caché. Y, por lo tanto, no hay necesidad de transferir los mismos datos nuevamente. 304 No modificado 4xx (categoría de error del cliente) Estos códigos de estado representan que el cliente ha realizado una solicitud defectuosa. indica que la solicitud del cliente no se procesó, ya que el servidor no pudo entender lo que solicita el cliente. 400 Solicitud incorrecta indica que el cliente no tiene permiso para acceder a los recursos y debe volver a solicitarlo con las credenciales requeridas. 401 No autorizado indica que la solicitud es válida y el cliente está autenticado, pero al cliente no se le permite acceder a la página o al recurso por ningún motivo. Por ejemplo, a veces el cliente autorizado no puede acceder al directorio en el servidor. 403 Prohibido indica que el recurso solicitado no está disponible ahora. 404 No encontrado indica que el recurso solicitado ya no está disponible y se ha movido intencionalmente. 410 Gone 5xx (categoría de error del servidor) indica que la solicitud es válida, pero el servidor está totalmente confundido y se le pide que atienda alguna condición inesperada. 500 Error interno del servidor indica que el servidor está inactivo o no disponible para recibir y procesar la solicitud. Sobre todo si el servidor está en mantenimiento. 503 Servicio no disponible 5) Convención de mayúsculas y minúsculas del nombre de campo Puede seguir cualquier convención de mayúsculas y minúsculas, pero asegúrese de que sea coherente en toda la aplicación. Si el cuerpo de la solicitud o el tipo de respuesta es , siga camelCase para mantener la coherencia. JSON 6) Búsqueda, clasificación, filtrado y paginación Todas estas acciones son simplemente la consulta en un conjunto de datos. No habrá un nuevo conjunto de API para manejar estas acciones. Necesitamos agregar los parámetros de consulta con la API del método GET. Comprendamos con algunos ejemplos cómo implementar estas acciones. En caso de que el cliente desee obtener la lista ordenada de empresas, el extremo debe aceptar varios parámetros de clasificación en la consulta. Por ejemplo clasificaría las empresas por su rango en orden ascendente. Clasificación GET /companies GET /companies?sort=rank_asc Para filtrar el conjunto de datos, podemos pasar varias opciones a través de los parámetros de consulta. Por ejemplo filtraría los datos de la lista de empresas con la categoría de empresa de Banking y donde la ubicación es India. Filtrado GET /companies?category=banking&location=india Al buscar el nombre de la empresa en la lista de empresas, el extremo de la API debe ser Búsqueda GET /companies?search=Digital Mckinsey Cuando el conjunto de datos es demasiado grande, lo dividimos en partes más pequeñas, lo que ayuda a mejorar el rendimiento y facilita el manejo de la respuesta. P.ej. significa obtener la lista de empresas en la página 23. Paginación GET /companies?page=23 Si agregar muchos parámetros de consulta en los métodos GET hace que el URI sea demasiado largo, el servidor puede responder con un estado HTTP ; en esos casos, los parámetros también se pueden pasar en el cuerpo de la solicitud del método . 414 URI Too long POST 7) Versión Cuando sus API están siendo consumidas por el mundo, actualizar las API con algún cambio importante también conduciría a romper los productos o servicios existentes que usan sus API. es un buen ejemplo, que tiene el número de versión de la API en la ruta. Si hay alguna actualización importante, podemos nombrar el nuevo conjunto de API como o http://api.yourservice.com/v1/companies/34/employees v2 v1.xx Estas pautas se compilan en mi experiencia de desarrollo. Me encantaría conocer sus puntos de vista sobre los puntos mencionados anteriormente. ¡Por favor, deja un comentario y hazme saber! Si este artículo te ayudó, entonces puedes 😊 invitarme a un café
