Restful API

Tomado de geek-and-poke

El primer paso para diseñar un API Rest es identificar los recursos que la aplicación maneja o va a manejar. Para esto podemos utilizar el listado inicial de requerimientos funcionales de la aplicación y el diagrama de clases que representa los conceptos principales que la aplicación debe manejar y las relaciones entre ellos.

Ejemplo Book: Diagrama Conceptual

En Ejemplo Book tenemos tres recursos raíz: books, authors y editorials. Cada uno representa la colección de libros, autores y editoriales respectivamente. Los reviews no son recursos raíz porque son dependientes del libro al que pertenecen.

Los servicios básicos asociados con los recursos raíz utilizando los verbos del protocolo HTTP son:

Servicio sobre el recurso books
Get /books retorna la colección de libros.
Post /books agrega un nuevo libro a la colección.
Put /books no se implementa.
Get /books/id retorna un libro con identificador id.
Post /books/id no se implementa.
Put /books/id modifica el libro con identificador id.
Delete /books/id borra el libro con identificador id.

En el diseño de este API, los recursos se representan como objetos JSON. Sin embargo, en cada caso es importante diseñar cuál es la información del recurso que se está enviando (en el caso de Post y Put) o retornando (en el caso de Get).

Representaciones

Para las aplicaciones de nuestros ejemplos, hemos tomado la decisión de diseño en donde para cada recurso hay dos representaciones JSON diferentes :

  • Básica Contiene los atributos propios de la clase.
  • Detallada Contiene los atributos de la representación Básica y las representaciones básicas de las relaciones.

Representaciones del recurso book

Tomando como partida el diagrama de clases de UML presentado más arriba, tenemos que la clase Book tiene relaciones con otras clases: Author, Review y Editorial.

Representación básica recurso book

La representación básica para cada recurso contiene los atributos de la clase y la representación básica de las clases con las que se tienen relaciones uno-a-uno y muchos-a-uno.

Para el recurso book, la representación básica incluye los atributos de la clase Book y la representación básica del objeto Editorial con el que se relaciona.

{ id: '' /*Tipo Long*/, name: '' /*Tipo String*/, isbn: '' /*Tipo String*/, description: '' /*Tipo String*/, image: '' /*Tipo String*/, publishingdate: '' /*Tipo Date*/ editorial: { id: '' /*Tipo Long*/, name: '' /*Tipo String*/ } }

Este es un ejemplo de una representación básica de Book.

{ "id" : 1, "name" : "Cien años de soledad", "description": "El libro se compone de 20 capítulos no titulados, en los cuales se narra una historia con una estructura cíclica temporal, puesto que los acontecimientos del pueblo y de la familia Buendía, así como los nombres de los personajes, se repiten una y otra vez, fusionando la fantasía con la realidad.", "isbn" : "0307474720", "image" : "http://goo.gl/IWNdCX", "publishDate" : "01071967", "editorial": {"id" : 1, "name" : "Plaza y Janes"} }

Representación Detallada

En los proyectos de ejemplo del curso, la representación detallada incluye los atributos de la clase y los datos (en representación básica) de todas las otras clases con las que se relaciona.

Esta es la representación detallada para la clase Book. Note que incluye los datos de una Editorial, así como un listado de Reviews y de Authors.

{ id: '' /*Tipo Long*/, name: '' /*Tipo String*/, source: '' /*Tipo String*/, description: '' /*Tipo String*/ , editorial: { id: '' /*Tipo Long*/, name: '' /*Tipo String*/ } reviews: [ {id: '' /*Tipo Long*/, name: '' /*Tipo String*/, source: '' /*Tipo String*/, description: '' /*Tipo String*/} ], authors:[ {id: '' /*Tipo Long*/, name: '' /*Tipo String*/, birthdate: '' /*Tipo String con formato fecha*/} ] }

Este es un ejemplo de una representación detalalda de Book.

{ "id" : 1, "name" : "Cien años de soledad", "description": "El libro se compone de 20 capítulos no titulados, en los cuales se narra una historia con una estructura cíclica temporal, puesto que los acontecimientos del pueblo y de la familia Buendía, así como los nombres de los personajes, se repiten una y otra vez, fusionando la fantasía con la realidad.", "isbn" : "0307474720", "image" : "http://goo.gl/IWNdCX", "publishDate" : "01071967", "editorial": {"id" : 1, "name" : "Plaza y Janes"}, "authors":[ { "id": 200, "name": "Gabriel José de la Concordia García Márquez" "birthDate": "1927-03-03T00:00:00-05:00", "description": "fue un escritor, guionista, editor y periodista colombiano. En 1982 recibió el Premio Nobel de Literatura.", "image": "https://commons.wikimedia.org/wiki/File:Gabriel_Garcia_Marquez.jpg", } ], "reviews":[ { "id": 123, "name": "Primera edición", "source":"El Tiempo", "description":"Magnifico inigualable" }, { "id": 456, "name": "Realismo", "source":"Arcadia", "description":"Realismo mágico al extremo. No puede dejar de leerlo." } ] }

Las otras representaciones de los recursos del ejemplo las puede revisar aquí

results matching ""

    No results matching ""