7 Buenas prácticas del diseño de APIs RESTful

El curso es simplemente otro más del montón sobre el tema. Me dedico a detallar:

1. No demuestran verdaderas APIs RESTful (consultar recurso: https://www.crummy.com/writing/speaking/2008-QCon/act3.html)
2. La técnica acá usada es a super bajo nivel al punto de que se muestra más peculiaridades de llamadas de bajo nivel con CUrl en PHP que REST como tal.
3. Dan malos consejos como el versionamiento de una API (ver imagen adjunta)
4. Por ningún lado mencionan Hypermedia ni HATEOAS (https://en.wikipedia.org/wiki/HATEOAS)
5. Contribuyen a la desinformación del estilo de arquitectura REST

Sobre el versionamiento

Les comparto algunas notas tomadas durante el curso. Notas

Se limitaron a hacer un simple CRUD de bajo nivel con PHP y JSON.

Lo peligroso y lamentable de esto es que quien no sabe del tema está super contento con lo acá aprendido y se va por el mundo creyendo que sabe REST, y no es así.

Los que tenemos más conocimientos en el tema porque vamos más allá de blogs escritos por el JS developer de turno sin formación en ciencias de la computación y 6 meses haciendo paginitas web,y en su lugar hemos profundizado en el tema, leído artículos de investigación, la disertación de Roy Fielding que da nacimiento a REST… sabemos que un nombre más apropiado para este curso debió ser “Cómo desarrolar servicios CRUD con JSON en PHP”.

¿Quieren ver algo realmente RESTful? Miren este video: https://vimeo.com/20781278

También quiero agregar una muy buena practica y es que si el servidor maneja mas de un recurso, lo suyo es usar un basepath, que normalmente viene con el versionado, ejemplo:

https://misitio.com/serviciosbancarios/v1/transferencias/
https://misitio.com/serviciosbancarios/v1/pagoprovedores/
https://misitio.com/serviciosbancarios/v1/nominas/

Aqui la estructura es: protocolo://misitioweb/basepath/versionado/recurso

7 Buenas prácticas del diseño de APIs RESTful

1. Siempre utiliza sustantivos para nombrar tus recursos.
2. Añade los nombres en plural para las urls.
3. Las modificaciones a recursos deben hacerse con su verbo HTTP correspondiente: POST, PUT o DELETE.
4. Para devolver recursos asociados a otro recurso utiliza url que incorporen subrecursos: /Autos/1/Choferes.
5. Navegabilidad vía vínculos.
6. Cuando devuelvas colecciones deben ser filtrables, ordenables y paginables.
7. Versiona tu API, añade el número de versión en la url: v1/Autos.

REST

REST no es un protocolo ni un estándar, sino que se trata de un conjunto de principios de arquitectura. Los desarrolladores de las API pueden implementarlo de distintas maneras.
 

Cuando se envía una solicitud a través de una API de RESTful, esta transfiere una representación del estado del recurso requerido a quien lo haya solicitado. La información se entrega por medio de HTTP en uno de estos formatos: JSON (Javascript Object Notation), HTML, XLT o texto sin formato. JSON es el más popular, ya que tanto las máquinas como las personas lo pueden comprender y no depende de ningún lenguaje.
 

Para que una API se considere de RESTful, debe cumplir los siguientes criterios:
 

• Arquitectura cliente-servidor compuesta de clientes, servidores y recursos, con la gestión de solicitudes a través de HTTP.
   

• Comunicación entre el cliente y el servidor sin estado, así que no se almacena la información del cliente entre las solicitudes; cada una es independiente y está desconectada del resto.
   

• Datos que pueden almacenarse en caché y optimizan las interacciones entre el cliente y el servidor.
   

• Una interfaz uniforme entre los elementos, para que la información se transfiera de forma estandarizada. Para ello deben cumplirse las siguientes condiciones:
   

  • Los recursos solicitados deben ser identificables e independientes de las representaciones enviadas al cliente.
     
  • El cliente debe poder manipular los recursos a través de la representación que recibe, ya que esta contiene suficiente información para permitirlo.
     
  • Los mensajes autodescriptivos que se envíen al cliente deben contener la información necesaria para describir cómo debe procesarla.
     
  • Debe contener hipermedios, lo cual significa que cuando el cliente acceda a cierto recurso, debe poder utilizar hipervínculos para buscar las demás acciones disponibles en ese momento.
     

• Un sistema en capas que organiza en jerarquías invisibles para el cliente cada uno de los servidores (los encargados de la seguridad, del equilibrio de carga, etc.) que participan en la recuperación de la información solicitada.
   

• Código disponible según se solicite (opcional), es decir, la capacidad de enviar código ejecutable del servidor al cliente cuando se solicite, lo cual amplía las funciones del cliente.
   
  Si bien la API de REST debe cumplir todos estos parámetros, resulta más fácil de usar que un protocolo definido previamente, como SOAP (protocolo simple de acceso a objetos), el cual tiene requisitos específicos, como la mensajería XML y la seguridad y el cumplimiento de las operaciones integrados, que lo hacen más lento y pesado.
   
  Por el contrario, REST es un conjunto de pautas que pueden implementarse según sea necesario. Por esa razón, las API de REST son más rápidas y ligeras, y resultan ideales para el Internet de las Cosas (IoT) y el desarrollo de aplicaciones para dispositivos móviles.
   
  What is a REST API

Un curso que sin duda necesita actualización o cambio de nombre por Fundamentos de API RESTful. Y hacer otro llamado Curso práctico de API RESTful.

En el curso de Introducción a Laravel hay un proyecto de una API con TDD muy bueno.

¿Quieren ver algo realmente RESTful? Miren este video: https://vimeo.com/20781278

Seria buena idea que se agregarán ejemplos a cada uno de los puntos de las buenas prácticas. En especial me interesa cuando menciona que al devolver colecciones deban ser filtrables, paginables y ordenables.

😮 lo del versionado no lo sabia.
Comenzare a implementarlo

Gracias platzi justo lo que necesito en mi trabajo,

¡Genial! Me gustó mucho el curso, más que nada fue un curso de fundamentos de API REST, ya que vimos cómo funcionaba por detrás todo este tema, me gustaría profundizar más en todo esto.

Por cierto, algo que recomiendo muchísimo es el curso de Postman, ese curso se puede complementar muy bien con este ^^

Veo opiniones debatidas sobre este curso, en lo personal a mi me pareció bueno ya que no conocía nada de REST. Al menos tengo ahora una idea y podré seguir investigando por mi cuenta. Es un buen inicio para conocer esta tecnología. Muy bueno!

Este curso es uno de los mejores cursos que he tomado hasta el momento en Platzi. Pude poner en práctica HTML, Bootstrap, JQUERY, JSON, Javascript, Bases de datos. Me deja muchas ganas de seguir aprendiendo y construir mi propia API! 😃😃😃

Muchas gracias Mauro!

Personalmente creo que el curso contiene lo básico para entender parte del gran mundo de API REST, con los conceptos y explicaciones que da el profesor debemos seguir investigando por nuestra cuenta para seguir aprendiendo.

Recursos = Sustantivos, siempre las URLs en Plurar.
Colecciones deben ser Filtrables,Ordenables y paginables por medio de parametros

muy buen curso sobre api from scratch

Info acerca de versionar

https://restfulapi.net/versioning/

Para la creación de una API profesional con PHP les recomiendo el framework lumen.

¿ Comó sería el endpoint cuando quiero realizar una acción ?
/employees/take-joboffert por ejemplo está?

Me encantó este curso 😄

Muy buen curso!!!

El curso estuvo genial, el conocimiento básico que se debe tener, las normas para unas buenas practicas de diseño de API’s e incluso el deploy con now fue increible, 😄

Me gustó el enfoque temático del curso (que es lo importante). Pero particularmente lo que me desagradó fue que diga “ei pi ai” en lugar de API tal y como suena. Bajo esa lógica; curl, http, rest, ful, también tendría que haberlo deletrado en inglés.

Excelente

Muy buenos consejos y practicas. numero conocimientos para mejorar mis Apis 😃

Les dejo mi github:
https://github.com/ruben-xe

Muy buen curso, un gran profesor. Gracias.

espero alguien me pueda ayudar y bueno que mi link también ayude a alguien https://platzi.com/r/christianfer/

Excelente curso…

• Nombre de recursos: Sustantivos
• Url plurales
• Modificaciones con PUT, POST y DELETE
• Usa URL que involucran subrecursos
• Navegabilidad vía vínculos
• Colecciones filtrables, ordenables y paginables
• Versiona tu API

• Siempre utiliza sustantivos para nombrar los recursos. Nunca verbos.
• En las URL siempre utiliza los slug en plural
• En aquellas operaciones que alteren los estados de los recursos utiliza los verbos HTTP que corresponde como PUT, POST o DELETE. Nunca GET.
• Para devolver recursos asociados a otro recurso utiliza url que incorporen subrecursos: /Autos/1/Choferes.
• Navegabilidad vía vínculos.
• Cuando devuelvas colecciones deben ser filtrables, ordenables y paginables.
• Versiona tu API, añade el número de versión en la url: v1/Autos.

Ame el curso 😁

Muy buen curso instructor Mauro, me agrado bastante que abarco la explicación de los conceptos iniciales, el uso de la terminal para realizar las consultas y los distintos detalles a tener en cuenta al desarrollar una API como las restricciones, manejo de errores y recomendaciones para nombrar rutas.

¡Ayuda por favor!
Ya instalé el más reciente Nodejs, el más reciente Now, pero aún así me sigue generando este error:

The Runtime @now/php is using nodejs8.10, which was discontinued by an upstream provider. In turn, we have to ask you to upgrade your Runtime to a more recent version or consult the author for more details.```

¿Cómo se soluciona?