API REST

Tabla de contenidos

• Introducción
• API
• Entidad Viajero
• Entidad Itinerario
• Entidad Ciudad
• Entidad Sitio de Interés
• Entidad Evento
• Entidad Hotel

API Rest

Introducción

La comunicación entre cliente y servidor se realiza intercambiando objetos JSON. Para cada entidad se hace un mapeo a JSON, donde cada uno de sus atributos se transforma en una propiedad de un objeto JSON. Todos los servicios se generan en la URL /misvacaciones.api/api/. Por defecto, todas las entidades tienen un atributo id, con el cual se identifica cada registro:

{
    id: '',
    attribute_1: '',
    attribute_2: '',
    ...
    attribute_n: ''
}

Cuando se transmite información sobre un registro específico, se realiza enviando un objeto con la estructura mencionada en la sección anterior. La única excepción se presenta al solicitar al servidor una lista de los registros en la base de datos, que incluye información adicional para manejar paginación de lado del servidor en el header X-Total-Count y los registros se envían en el cuerpo del mensaje como un arreglo.

La respuesta del servidor al solicitar una colección presenta el siguiente formato:

[{}, {}, {}, {}, {}, {}]

Tabla de convenciones (representaciónes JSON)

|Tipo| Definición| Convención |:--:|:--:|:--:|:--:|:--:|:--:| |Minimum| Contiene únicamente los atributos de la clase.|(M)| | | |Basic| Contiene todo lo de la representación Minimum y las relaciones muchos a uno y uno a uno| (B)| |Full| Contiene todo lo de la representación Basic y las colecciones composite|(F)||

API de la aplicación MisVacaciones

Entidad Viajero

Estructura de objeto Viajero

{
    id: '' /*Tipo Long*/, /*autogenerado*/
    nombre: '' /*Tipo String*/,
    correo: '' /*Tipo String*/,
    contrasena: '' /*Tipo String*/,
    foto (URL): '' /*Tipo String*/
}

Servicios

Método	URL	Acción	Parámetros	Cuerpo	Retorno
GET	/viajeros (F)	Lista los registros de Viajero (READ)	@QueryParam page: muestra todos los viajeros
GET	/viajeros/:viajeroId (B)	Obtener los atributos de una instancia de Viajero(READ)	@PathParam viajeroId: Identificador del viajero		Atributos de la instancia de Viajero
POST	/viajeros (F)	Crear una nueva instancia de la entidad Viajero (CREATE)		Atributos de la instancia de Viajero a crear:nombre, correo, contrasena, foto (URL)	Instancia de Viajero creada, incluyendo su nuevo ID autogenerado
PUT	/viajeros/:viajeroId (M)	Actualiza una instancia de la entidad Viajero (UPDATE)	@PathParam viajeroId: Identificador del viajero	Objeto JSON de Viajero	Instancia de Viajero actualizada
DELETE	/viajeros/:viajeroId (F)	Borra instancia de Viajero en el servidor (DELETE)	@PathParam viajeroId: Identificador del viajero	@PathParam viajeroId: Identificador de instancia de viajero

Volver arriba

Entidad Itinerario

Estructura de objeto Itinerario

{
    id: '' /*Tipo Long*/, 
    viajero: '' /*Tipo String*/, 
    nombre: '' /*Tipo String*/,
    fecha_inicio: '' /*Tipo String*/,
    fecha_fin: '' /*Tipo String*/,
    ciudades: [] /*Colección de registros de Ciudad*/
}

//Ciudad
{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    detalles: '' /*Tipo String*/,
    fInicio: '' /*Tipo Date*/,
    fFin: '' /*Tipo Date*/,
    imagen: '' /*Tipo String*/,
    sitios: [] /*Colección de registros de SitioDeInteres*/
    eventos: [] /*Colección de registros de Evento*/
}

//SitioDeInteres
{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    detalles: '' /*Tipo String*/,
    imagen: '' /*Tipo String*/,
    fecha: '' /*Tipo Date*/
}

//Evento
{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    detalles: '' /*Tipo String*/,
    fecha: '' /*Tipo Date*/
}

Servicios

Método	URI	Acción	Parámetros	Cuerpo	Retorno
GET	/itinerarios (M)	Lista los registros de Itinerario (READ)	@QueryParam page: página a consultar
GET	/itinerarios/:itinerarioId (F)	Obtener los atributos de una instancia de Itinerario(READ)	@PathParam itinerarioId: Identificador del registro		Atributos de la instancia de Itinerario
GET	/itinerarios/viajero/:viajeroId (M)	Lista los registros de Itinerario asociados a un viajero particular(READ)	@PathParam viajeroId: Identificador del viajero
POST	/itinerarios (B)	Crear una nueva instancia de la entidad Itinerario (CREATE)		Atributos de la instancia de Itinerario a crear	Instancia de Itinerario creada, incluyendo su nuevo ID
PUT	/itinerarios/:itinerarioId (B)	Actualiza una instancia de la entidad Itinerario (UPDATE)	@PathParam itinerarioId: Identificador del registro	Objeto JSON de Itinerario	Instancia de Itinerario actualizada
DELETE	/itinerarios/:itinerarioId (B)	Borra instancia de Itinerario en el servidor (DELETE)	@PathParam itinerarioId: Identificador del registro
GET	/itinerarios/:itinerarioId/ciudades (M)	Lista las ciudades del itinerario (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere listar las ciudades		Lista de las instancias de ciudad
GET	/itinerarios/:itinerarioId/ciudades/:ciudadID (F)	Obtener los atributos de una instancia de Ciudad (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere obtener la ciudad @PathParam itinerarioId: Identificador de la ciudad que se quiere obtener		Atributos de la instancia de ciudad
POST	/itinerarios/:itinerarioId/ciudades (B)	Crear una nueva instancia de la entidad Ciudad (CREATE)	@PathParam itinerarioId: Identificador del itinerario en el que se quiere crear la ciudad	Atributos de la instancia de Ciudad a crear	Instancia de Ciudad creada, incluyendo su nuevo ID
PUT	/itinerarios/:itinerarioId/ciudades/:ciudadId (B)	Actualiza una instancia de la entidad Ciudad en un itinerario (UPDATE)	@PathParam itinerarioId: Identificador del itinerario @PathParam ciudadId: Identificador de la ciudad	Objeto JSON de Ciudad	Instancia de Ciudad en Itinerario actualizada
DELETE	/itinerarios/:itinerarioId/ciudades/:ciudadId (B)	Borra instancia de la entidad Ciudad asociado al Itinerario en el servidor (DELETE)	@PathParam itinerarioId: Identificador del registro @PathParam ciudadId: Identificador de la ciudad que se desea eliminar
GET	/itinerarios/:itinerarioId/ciudades/:ciudadid/eventos (M)	Lista los eventos en la ciudad del itinerario (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere listar los eventos @PathParam ciudadId: Identificador de la ciudad de la que se quiere listar los eventos		Lista de las instancias de evento
GET	/itinerarios/:itinerarioId/ciudades/:ciudadId/eventos/:eventoId (F)	Obtener los atributos de una instancia de Evento (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere obtener el evento @PathParam itinerarioId: Identificador de la ciudad de la que se quiere obtener el evento @PathParam eventoId: Identificador del evento que se quiere obtener		Atributos de la instancia de evento
POST	/itinerarios/:itinerarioId/ciudades/:ciudadId/eventos (B)	Crear una nueva instancia de la entidad Evento (CREATE)	@PathParam itinerarioId: Identificador del itinerario en la que se encuentra la ciudad en donde se quiere crear el Evento @PathParam ciudadId: Identificador de la ciudad en la que se quiere crear el Evento	Atributos de la instancia de Evento a crear	Instancia de Evento creada, incluyendo su nuevo ID
DELETE	/itinerarios/:itinerarioId/ciudades/:ciudadId/eventos/:eventoId (B)	Borrar instancia de la entidad Evento (DELETE) asociada al itinerario y ciudad especificados	@PathParam itinerarioId: Identificador del itinerario en la que se encuentra la ciudad en donde se quiere eliminar el Evento @PathParam ciudadId: Identificador de la ciudad en la que se quiere eliminar el Evento @PathParam eventoId: Identificador del Evento que se quiere eliminar
GET	/itinerarios/:itinerarioId/ciudades/:ciudadId/sitios (M)	Lista los sitios en la ciudad del itinerario (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere listar los sitios @PathParam ciudadId: Identificador de la ciudad de la que se quiere listar los sitios		Lista de las instancias de sitio
GET	/itinerarios/:itinerarioId/ciudades/:ciudadId/sitios/:sitioId (F)	Obtener los atributos de una instancia de Sitio de Interés (READ)	@PathParam itinerarioId: Identificador del itinerario del que se quiere obtener el sitio @PathParam ciudadId: Identificador de la ciudad de la que se quiere obtener el sitio @PathParam sitioId: Identificador del sitio que se quiere obtener		Atributos de la instancia de sitio
POST	/itinerarios/:itinerarioId/ciudades/:ciudadId/sitios (B)	Crear una nueva instancia de la entidad Sitio de interés (CREATE)	@PathParam itinerarioId: Identificador del itinerario en la que se encuentra la ciudad en donde se quiere crear el sitio de interés @PathParam ciudadId: Identificador de la ciudad en la que se quiere crear el sitio de interés	Atributos de la instancia de Sitio de interés a crear	Instancia de Sitio de interés creada, incluyendo su nuevo ID
DELETE	/itinerarios/:itinerarioId/ciudades/:ciudadId/sitios/:sitioId (B)	Borrar instancia de la entidad Sitio de interés (DELETE) asociada al itinerario y ciudad especificados	@PathParam itinerarioId: Identificador del itinerario en la que se encuentra la ciudad en donde se quiere eliminar el Sitio de interés @PathParam ciudadId: Identificador de la ciudad en la que se quiere eliminar el Sitio de interés @PathParam sitioId: Identificador del Sitio de interés que se quiere eliminar

Volver arriba

Entidad Ciudad

Estructura de objeto Ciudad

{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    foto: '' /*Tipo String*/,
    descripcion: '' /*Tipo String*/,
    sitios_de_interes: [] /*Colección de registros de SitioDeInteres*/
    eventos: [] /*Colección de registros de Evento*/
    hoteles: [] /*Colección de registros de Hotel*/
}

Servicios

Método	URI	Acción	Parámetros	Cuerpo	Retorno
GET	/ciudades (B)	Lista los registros de Ciudad (READ)	@QueryParam page: página a consultar
GET	/ciudades/:ciudadid (F)	Obtener los atributos de una instancia de Ciudad(READ)	@PathParam ciudadid: Identificador del registro		Atributos de la instancia de Ciudad
POST	/ciudades (F)	Crear una nueva instancia de la entidad Ciudad (CREATE)		Atributos de la instancia de Ciudad a crear	Instancia de Ciudad creada, incluyendo su nuevo ID
PUT	/ciudades/:ciudadid (F,Integer)	Actualiza una instancia de la entidad Ciudad (UPDATE)	@PathParam ciudadid: Identificador del registro	Objeto JSON de Viajero	Instancia de Viajero actualizada
DELETE	/ciudades/:ciudadid (Integer)	Borra instancia de Ciudad en el servidor (DELETE)	@PathParam ciudadid: Identificador del registro	@PathParam ciudadid: Identificador de instancia de Ciudad	Lista de registros de ciudades(Ciudad)

Volver arriba

Entidad Evento

Estructura de objeto Evento

{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    fecha: '' /*Tipo Date*/,
    detalles: '' /*Tipo String*/,
    imagen: '' /*Tipo String*/
}

Servicios

Método	URI	Acción	Parámetros	Cuerpo	Retorno
GET	/ciudades/:ciudadid/eventos (Integer,B)	Muestra los eventos existentes (Read)	@QueryParam page: página a consultar @PathParam ciudadid: Identificador de la ciudad de la cual se quieren mostrar los eventos
GET	/ciudades/:ciudadid/eventos/:eventoid (Integer,Integer,F)	Muestra en detalle todos los atributos acerca de un evento (Read)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere buscar el evento @PathParam eventoid: Identificador del registro		Atributos de la instancia de evento
POST	/ciudades/:ciudadid/eventos/ (Integer, (F) eventos)	Crea un nuevo evento en la ciudad que se desee (Create)	@PathParam ciudadid: Identificador de la ciudad en la que se quiere crear el evento	Atributos del evento a crear	Nuevo evento creado, incluyendo su nuevo ID
PUT	/ciudades/:ciudadid/eventos/:eventoid (F)	Actualiza la instancia de un evento en especifico (Update)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere actualizar el evento @PathParam eventoid: Identificador del registro	Objeto JSON de Viajero	Instancia de Viajero actualizada
DELETE	/ciudades/:ciudadid/eventos/:eventoid (Integer,Integer)	Borra un evento en el servidor (Delete)	@PathParam eventoid: Identificador del evento a eliminar**@PathParam ciudadid**: Identificador de la ciudad de la que se quiere eliminar el evento		Lista de registros de Eventos (Eventos)

Volver arriba

Entidad Sitio de interés

Estructura de objeto Sitio de interés

{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/,
    detalles: '' /*Tipo String*/,
    imagen: '' /*Tipo String*/
}

Servicios

Método	URI	Acción	Parámetros	Cuerpo	Retorno
GET	/ciudades/:ciudadid/sitios (Integer,B)	Lista los registros de Sitio de interés (READ)	@QueryParam page: página a consultar @PathParam ciudadid: Identificador de la ciudad de la que se quieren ver los sitios de interés
GET	/ciudades/:ciudadid/sitios/:sitioid (Integer,Integer,F)	Obtener los atributos de una instancia de Sitio de interés (READ)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere ver el sitio de interés @PathParam sitioid: Identificador del registro		Atributos de la instancia de Sitio de interés
POST	/ciudades/:ciudadid/sitios/ (Integer, (F) sitios)	Crear una nueva instancia de la entidad Sitio de interés (CREATE)	@PathParam ciudadid: Identificador de la ciudad en la que se quiere crear el sitio de interés	Atributos de la instancia de Sitio de interés a crear	Instancia de Sitio de interés creada, incluyendo su nuevo ID
PUT	/ciudades/:ciudadid/sitios/:sitioid (F)	Actualiza una instancia de la entidad Sitio de interés (UPDATE)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere actualizar el sitio de interés @PathParam sitioid: Identificador del registro	Objeto JSON de Viajero	Instancia de Viajero actualizada
DELETE	/ciudades/:ciudadid/sitios/:sitioid (Integer,Integer)	Borra instancia de Sitio de interés en el servidor (DELETE)	@PathParam sitioid: Identificador de instancia de Sitio de interés @PathParam sitioid: Identificador de la ciudad de la que se quiere eliminar el sitio de interés		Lista de registros de Sitios de interés (Sitio de Interés)

Volver arriba

Entidad Hotel

Estructura de objeto Hotel

{
    id: '' /*Tipo Long*/, 
    nombre: '' /*Tipo String*/, 
    direccion: '' /*Tipo String*/,
    descripcion: '' /*Tipo String*/,
    numero_de_estrellas: '' /*Tipo Int*/
}

Servicios

Método	URI	Acción	Parámetros	Cuerpo	Retorno
GET	/ciudades/:ciudadid/hoteles	Lista los registros de Hotel (READ)	@QueryParam page: página a consultar @PathParam ciudadid: Identificador de la ciudad de la que se quieren ver los hoteles
GET	/ciudades/:ciudadid/hoteles/:hotelid	Obtener los atributos de una instancia de Hotel (READ)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere ver el hotel @PathParam hotelid: Identificador del registro		Atributos de la instancia de Hotel
POST	/ciudades/:ciudadid/hoteles/	Crear una nueva instancia de la entidad Hotel (CREATE)	@PathParam ciudadid: Identificador de la ciudad en la que se quiere crear el hotel	Atributos de la instancia de Hotel a crear	Instancia de Hotel creada, incluyendo su nuevo ID
PUT	/ciudades/:ciudadid/hoteles/:hotelid	Actualiza una instancia de la entidad Hotel (UPDATE)	@PathParam ciudadid: Identificador de la ciudad de la que se quiere actualizar el hotel @PathParam hotelid: Identificador del registro	Objeto JSON de Viajero	Instancia de Viajero actualizada
DELETE	/ciudades/:ciudadid/hoteles/:hotelid	Borra instancia de Hotel en el servidor (DELETE)	@PathParam hotelid: Identificador de instancia de Hotel @PathParam ciudadid: Identificador de la ciudad de la que se quiere eliminar el hotel		Lista de registros de hoteles (Hotel)

Volver arriba