Platzi
Platzi

¡Invierte en ti y celebremos! Adquiere un plan Expert o Expert+ a precio especial.

Antes: $349
$259
Currency
Antes: $349
Ahorras: $90
COMIENZA AHORA
Termina en: 9D : 3H : 41M : 2S
Curso de Postman

Curso de Postman

Eduardo Álvarez

Eduardo Álvarez

Estructuras de las URLs

3/17

Lectura

En un API es importante tener bien estructuradas las rutas por las cuales se usarán cada uno de los endpoints que contiene. Antes de entrar de lleno a explicar el API con el que trabajaremos en este curso veamos unos conceptos muy importantes a la hora de trabajar con APIs.

Recurso

Es la instancia o la representación de un objeto o la representación de algo, tiene datos y operaciones asociadas a él. Por ejemplo: course, material y video son recursos que tenemos disponibles en el API con la que trabajaremos y podemos realizar operaciones sobre ellos: crear, actualizar y eliminar.

Colecciones

Es un conjunto de recursos, por ejemplo: courses es una colección de course.

URL

(Uniform Resource Locator) es la ruta en la cual puede ser ubicado un recurso y ejecutar las operaciones sobre él.

CRUD

Siglas que hacen referencia a las operaciones básicas que se pueden ejecutar sobre un recurso:

  • C: Create (crear)
  • R: Read (leer)
  • U: Update (actualizar)
  • D: Delete (eliminar)

Endpoints

Es el punto final de la comunicación con un ente, en este caso, un endpoint está asociado a una URL y a las operaciones que podemos ejecutar. Este término es muy utilizado en las APIs.

Los endpoint definen operaciones que se quieren ejecutar sobre un recurso. Por ejemplo: si queremos un conjunto de operaciones CRUD sobre Cursos podríamos crear los siguientes endpoints:

  • /get-all-courses : para obtener una colección de Cursos.
  • /add-new-course: para crear un nuevo recurso de Cursos.
  • /delete-all-courses: para eliminar todos los Cursos.

Y así sucesivamente. Pero, esto implicaría un problema. El API puede llenarse de endpoints que ejecutan una sola operación, esto no es escalable, significa que si por ejemplo el recurso Cursos pasa a llamarse Clases habría que actualizar absolutamente todas las URLs y asegurarse de ello puede convertirse en un dolor de cabeza.

Entonces, ¿cuál es la buena práctica en este caso?

Como lo vimos en la clase pasada, el protocolo HTTP especifica una serie de verbos que indican acciones. Lo ideal es que la operación que se ejecute sobre un recurso se obtenga a través del verbo HTTP de la petición y no que esté definido en el endpoint. Por ejemplo:

  • /courses: Dependiendo del verbo HTTP se ejecutará una operación en particular. Quedaría así:
    • GET /courses: trae la colección de Cursos.
    • POST /courses: crea un nuevo recurso de Cursos.
    • DELETE /courses: elimina todos los cursos.

De esta manera queda mucho más organizado un API. Pero, qué pasa si queremos traer no una colección de cursos como en los casos anteriores, sino un recurso en específico.

Por lo general cada recurso tiene un identificador único, un ID, es con esto que llamaremos a un endpoint para que nos retorne la información del recurso. Por ejemplo:

  • GET /courses/2/: vemos que acá se le está pasando algo que en los endpoints anteriores no veíamos, es el número 2, ese es el identificador único, de esta manera el API sabe que tiene que buscar el curso con ID 2 y retornarlo.

Así sucesivamente con cada uno de los verbos, por ejemplo: casi nunca se hace una eliminación en masa en un API, como el ejemplo que tenemos más arriba donde se eliminan todos los cursos. Lo ideal es que se elimine un recurso individualmente y no una colección, igualmente pasa con la actualización.

Recursos anidados

Hay veces en las que un recurso depende de otro recurso, por ejemplo, comentarios depende de materiales; usualmente en los APIs las anidaciones se hacen hasta dos niveles, es decir:

  • materials/1/comments: estos son dos niveles
  • materials/1/comments/2/answers/: son tres niveles, ahí lo ideal sería entonces separar el endpoint de comentarios y ejecutar comments/2/answers/

Nuestro API

Ya he dado algunos spoilers sobre lo que nuestro API hace, es un clon de lo que Platzi es, una plataforma es donde tenemos Cursos, Materiales, Videos y Comentarios. El API es sencillo y es una prueba que utilizamos en este curso para explorar toda las capacidades que nos ofrece Postman para trabajar con ellos.

Una convención que se usa a la hora de documentar APIs es abstraer el endpoint de la URL del sitio al cual vamos a hacer la petición, puesto que esto al final es redundante de escribir, es decir, usualmente escribimos únicamente /api-token-auth/ en vez de [http://mistioweb.com/api-token-auth/](http://mistioweb.com/api-token-auth/).

Los endpoints que tenemos:

  • /api-token-auth/
  • /courses
  • /courses/:id/
  • /courses/:id/upload_badge/
  • /materials/
  • /materials/:id/
  • /materials/:id/comments/
  • /comments/
  • /comments/:id/
  • /comments/:id/like/
  • /comments/:id/dislike/

En el curso de django avanzado hay una clase especial donde hablan sobre las mejores practicas https://platzi.com/clases/1461-django-avanzado/17199-buenas-practicas-para-el-diseno-de-un-api-rest/
Sin embargo yo les resumiré un poco:

Algunas buenas prácticas con las APIs:

Use sustantivos en lugar de verbos

Forma correcta
GET / books / 123
DELETE / books / 123
POST / books
PUT / books / 123
PATCH / books / 123

-vs-

Forma incorrecta GET / addBook123 (por cierto, GET solo debe usarse para LEER datos y nunca cambiar su estado de ninguna manera)
GET / DeleteBooks / 123
POST / DeleteAllBooks
POST / books / 123 / delete

Hay ciertos casos en los que está bien usar acciones de manera similar a la manipulación de recursos, por ejemplo:
PUT / accounts / 123 / activación

Dicha solicitud crea o actualiza una propiedad de activación a una cuenta ‘123’, en lugar de simplemente decir que se debe invocar el “activar”.

Es tentador usar algo como POST / activar_cuenta / 123 o PUT / cuenta / 123? Activar = verdadero, pero ambos son incorrectos.

Nombra las colecciones usando sustantivos plurales
Para las colecciones en el desarrollo de API REST, use sustantivos plurales. No es solo una buena práctica establecida. Realmente hace que sea más fácil para los humanos tener una idea de que algo es en realidad una colección.

P.ej.

GET / cars / 123
POST / cars
GET / cars
-vs-
GET / car / 123
POST / car
GET / car

Lo único que no estoy de acuerdo con este contenido es lo siguiente
GET /courses: trae la colección de Cursos.
POST /courses: crea un nuevo recurso de Cursos.
DELETE /courses: elimina todos los cursos.

Hace tiempo pensaba lo mismo con relación a esto pero luego de tener entrenamiento en seguridad me di cuenta que esta forma no es muy seguro de hacer porque sabemos que un recurso puede se repite en varios métodos.

Cuando parece que ya has entendido una cosa, descubres 10 cosas más que ni sabías que existían.

Tan bello como frustrante 😂

Excelente explicación, no conocia la estructura general de las API.

Me encantaria ver Postman orientado a los Test. La parte de automatizacion con Postman. Expectativa al ver el curso.

Como Ingeniero de calidad, esta información me da mucha claridad y visibilidad para poder realizar pruebas a endPoints

Es bastante interesante al igual que fácil de entender esta clase/articulo

Esta explicacion esta genial mejores que muchos tutoriales no tan especificos que estan en otras paginas por no nombrarlas

para mi todo esto es nuevo pero voy con fe y sin miedo

Esto es lo que necesitaba para fortalecer mi crud y mis conocimientos de API

Muy bueno que nos proporcione una API de ellos, se hace más ameno.

Excelente explicación, conocia algunos conceptos sobre APIs pero con esta lectura todo queda mucho mas claro.

Buen post, fácil de digerir, ahora a la práctica!

Había trabajado antes con Apis, en proyectos propios, Pero siempre veo que se aprenden cosas nuevas, la forma en como hace referencia a los End Points me parece clara.

Increíble, no tenía idea sobre la parte de endpoints del estilo add-new-course, sin duda usar los verbos HTTP hacen que sea más fácil el manejar estas acciones, y esto me sirve mucho porque después planeo tomar el curso de API REST ^^

Las deficniciones son muy claras y aplicables

Muy claros los conceptos.

Buenardo

Me parece que esta muy completa la infomacion

Excelente información!

todo esto es nuevo para mi.

Información robusta, pero demasiado interesante. Ya quiero empezar a trabajar con la API, la podré usar para practicas con js?

que buena información a profundizar más de conociemientos de APIs

Si en el backend tengo un endpoint que recibe recibe una solicitud de un dato, pero al buscar ese dato en la base de datos (o en otra api), recibo un error (por ejemplo, no se pudo acceder), que error debo devolver? un 500? cual de todos?

jeje super interesante.

Gracias, que buen resumen ahora ya conozco mas sobre APIs.

Muy bueno!

Muy buena información

Siempre estoy investigando y claramente esta informacion que exponen es una buena base para continuar aprendiendo, se les agradece la manera de entregar estos cursos de una manera rapida y efectiva, durariamos años en una universidad para llegar ha ver algo y quizas como opcional.

jn

Excelente aporte, muchas gracias.

San Buenardo!!!

Gran aporte Gracias.

Muchas Gracias, Excelente Artículo

Esto buscaba una explicación mas clara. Gracias

Esto deberían de colocarlo en todos lo cursos

Super, muy buena info.

muy claro

Me surge una serie de preguntas 1) Courses seria la colección?
2) “:id” y “id/upload_badge” serian Recursos anidados?
3) Es lo mismo un recurso que un EndPoint?.
Gracias.

Gracias! No sabía que se podían anidar y además que es medio mala práctica.

😀

Muy bien explicado.

Excelente explicación

Excelente documentación

interesante.

Quedo claro.

Vaya! Cuanta información. Gracias.

Tengo un año trabajando en un API que hice con Laravel y las practicas que hice no fueron buenas. Que bueno que estoy leyendo esto, ya se como hacer mejor mis próximos servicios.

Mucho por aprender.

Todo mas que claro, ha seguir. 😃

Este Curso pinta muy bien 😃

Tengo entendido que usar el all() es una mala practica para obtener datos. Pero, vamos a aprender más.

Hacia falta este glosario de términos para tener clara la terminología que se ira a usar a lo largo del curso. Quizás deba colocarse antes.

ahora si tengo mucho mas claro sobre estas terminologías que son muy importantes

Esto está muy bien estructurado y de muy buenas prácticas. Sigamos…

muy interesante todo este contenido

Excelente explicación!!!

Excelente!!

excelente

muy buena explicación

materials/1/comments/2/answers/ <-- no sé si realmente sea buena práctica colocar materials con su id acá. A menos que el comment de id “2” pertenezca a más de un “material”, “materials/1/” es redundante e innecesario

Excelente explicacion

Muy buena Explicacion

Creo que cuando termine este curso voy a crear Gabo-Land mi API personal ------

Aunque no está en la lectura, también entiendo que existe las opciones de extender o popular recursos en caso el cliente lo necesite, en consultas de recursos anidados donde hay un foreign key, se necesita obtener la data de ese recurso que está en otra tabla, un recurso que he visto es enviar query params, muy parecido para cuando quieres hacer paginación.

Todo muy bien explicado.

OMG, donde el curso siga así me voy a sobrecargar de contenido. Muchas gracias.

Buenas prácticas en éste contenido

totalmente entendido

muy buena info, ahora a usarla !!

Bueno ahora me queda claro que son los endpoints,gracias por el articulo

Muy bueno esta el articulo. ^^!

Muchas gracias por el articulo!

excelente!

Excelente artículo. La verdad, muchas veces había escuchado el término “API” pero hasta ahora, nunca había tomado contacto con alguna.

Algún curso para crear API REST?

excelente explicación

buena explicacion

me gusto la explicación porque se entiende lo de los niveles.

😮

Muy buena explicación!

Excelente explicación…este curso va a estar muy interesante 😃

Bueno ahora se que estaba diseniando mal la api

pero cuales son las credencial de authenticacion para esta api?

Practicas buenas con API ya creadas

Si quiero hace un UPDATE:
**PUT/courses ** ¿quedaría así?

Excelente…

Es fácil perder la vista de conjunto cuando se trabaja en el detalle. Este es un buen resumen y mirada general.

Buen resumen

Buena info, gracias

Que buen resumen, muy práctico y se entiende. 😃

Muy buen aporte conceptual

excelente

Hola, que pasa con los API’s que hacen acciones especificas, consultas complejas, dependiendo de ciertos parámetros, mas de 10 filtros seguimos usando get.