Curso de Postman 2020

Curso de Postman 2020

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/

Aportes 96

Preguntas 2

Ordenar por:

驴Quieres ver m谩s aportes, preguntas y respuestas de la comunidad? Crea una cuenta o inicia sesi贸n.

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 鈥渁ctivar鈥.

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

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

Tan bello como frustrante 馃槀

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

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 ^^

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

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

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.

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

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

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.

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 鈥渋d/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 鈥渕aterial鈥, 鈥渕aterials/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 鈥淎PI鈥 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鈥ste 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鈥檚 que hacen acciones especificas, consultas complejas, dependiendo de ciertos par谩metros, mas de 10 filtros seguimos usando get.