Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte II):

Siguiendo con las buenas prácticas RESTful Buenas Prácticas para diseñar una API RESTful-pragmatic (Parte I)

Hoy hablaremos del filtrado, ordenado y búsqueda.

Como primer criterio debemos contemplar mantener las URLS tan limpias como podamos, las búsquedas, filtrados,… se resuelven como parámetros de la query sobre la URL base.

Filtrado:

· Se usa un parámetro de la query único por cada campo que implementa el filtrado del recurso.

· Ejemplo GET /reclamaciones?state=open

Ordenado:

· Se usa un parámetro de la query genérico y predefinido para ordenado y algo para indicar si es ascendente o descendente

· Ejemplos GET /reclamaciones?sort=-createdAt GET /reclamaciones/sort=-createdAt,+updatedAt

Búsqueda:

· Se suele usar un parámetro de la query q o query

· Ejemplo GET /reclamaciones?q=saldo

Alias de consultas frecuentes

· Una técnica útil para hacer el API más usable para los consumidores es definir alias para consultas frecuentes

· Ejemplo GET /reclamaciones/recently_closed

Limitar los campos que devuelve el API

· Muchas veces el consumidor del API no necesita una representación completa del recurso. Esta funcionalidad minimiza el tráfico de red devolviendo sólo los datos necesarios. Se usa un parámetro estilo fields

· Ejemplo GET /reclamaciones/fields=id,reclamantes,descripción

Todo junto podría quedar GET/reclamaciones?q=saldo&state=open&sort=-createdAt&fields=id,reclamantes

¿Qué es RESTTemplate?

RESTTemplate es la clase que ofrece Spring para el acceso desde la parte cliente a Servicios REST.

Conceptualmente sería el equivalente al JdbcTemplate o al JmsTemplate.

¿Qué es UNIREST?

Los métodos principals de la clase corresponden con los métodos HTTP (falta el PATCH :))

Cada método toda como primer argumento una URI que puede ser una URI template s¡y se pueden usar variables para resolver el template, como se ve en este ejemplo:

String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/bookings/{booking}", String.class, "42", "21");

Esto mismo podría ejecutarse así:

Map<String, String> vars = new HashMap<String, String>();

vars.put("hotel", "42");

vars.put("booking", "21");

String result = restTemplate.getForObject("http://example.com/hotels/{hotel}/bookings/{booking}", String.class, vars);

Un ejemplo algo más complejo sería este:

final String photoSearchUrl = "http://www.flickr.com/services/rest?method=flickr.photos.search&api+key={api-key}&tags={tag}&per_page=10";

Source photos = restTemplate.getForObject(photoSearchUrl, Source.class, apiKey, searchTerm);

Que usa el SourceHttpMessageConverter para convertir el XML de respuesta hacia un javax.xml.transform.Source.

Leer más

Una alternativa al RESTTemplate es UNIREST.

A %d blogueros les gusta esto: