Introducción

El API de TelotriagodemiPueblo permite a un aplicativo cliente interactuar de forma transparente con los recursos de la misma mediante el protocolo HTTP y en la mayoría de los casos siguiendo una filosofía Rest.

Básicamente un usuario deberá registrarse en el sistema proporcionando entre otros datos, un usuario y una password que el sistema custodiará. Cuando dicho usuario desee interactuar con el sistema deberá proporcionar dichos datos para obtener un token, el cual tiene una validez determinada. El cliente deberá proporcionar este token en cada petición que haga tal como se explica en este documento.

Para la invocación de las APIs el cliente deberá identificarse previamente mediante una llamada a Login y guardar el token que se le proporciona para usarlo en futuras llamadas. Estas llamadas enviarán el token usando las cabeceras de la petición mediante el formato Bearer

De forma general, todas las peticiones incluirán las siguientes cabeceras en sus solicitudes:

Name Description

Authorization

Bearer auth credentials

Diagrama de secuencia donde un usuario anónimo desea identificarse en el sistema. Si la identificación es correcta obtendrá un token para usar en futuras peticiones

secuencia login

Diagrama de secuencia donde un usuario identificado previamente y que disponde de un token, desea acceder a un recurso protegido (por ejemplo ver sus mensajes)

secuencia login

HTTP verbs

El API intenta cumplir el standard HTTP y las convenciones sobre verbos de REST al máximo

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, overwrites all fields

PATCH

Used for partial updates to an existing resource

DELETE

Used to delete an existing resource

HTTP status codes

El API intenta cumplir el standard HTTP y las convenciones sobre códigos de retorno de REST al máximo

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

404 Not Found

The requested resource did not exist

405 Method Not Allowed

The type of request for this resource is not allowed. For example, some endpoints may be GET only. Trying a POST will return this message.

422 Unprocessable Entity

There was an error in the request. The response body will contain the error message.

APIs básicas

Las APIs básicas son aquellas que permiten las acciones mínimas para acceder al sistema, como son el registro, el login y obtener el perfil del usuario.

/registration

Para el registro de usuarios se dispone de las siguientes APIS

Alta de un usuario nuevo

Campos de solicitud:

Path Type Description

nombre

String

el nombre del usuario

username

String

el identificado de usuario

password

String

la clave del usuario

Campos de respuesta:

Path Type Description

timestamp

Number

el instante en el que se crea el usuario

status

Number

codigo de estado

error

String

mensaje de error

message

String

mensaje de resultado

path

String

ruta solicitada

Ejemplo:

$ echo '{
  "nombre" : "615679348",
  "username" : "615679348@test.com",
  "password" : "615679348"
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/registration' 'Accept:application/json' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 201 Created
Date: Wed, 21 Dec 2016 22:13:51 GMT
X-Application-Context: application:test:0
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 127

{
  "error" : "Created",
  "message" : "Created",
  "path" : "/registration",
  "status" : 201,
  "timestamp" : 1482358431473
}

Usuario ya existente

Si el usuario ya existe el sistema devolverá el correspondiente error HTTP 409:

$ echo '{
  "nombre" : "615679348",
  "username" : "615679348@test.com",
  "password" : "615679348"
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/registration' 'Accept:application/json' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 409 Conflict
Date: Wed, 21 Dec 2016 22:13:51 GMT
X-Application-Context: application:test:0
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 129

{
  "error" : "Conflict",
  "message" : "Conflict",
  "path" : "/registration",
  "status" : 409,
  "timestamp" : 1482358431563
}

/api/login

Para la identificación de un usuario se dispone del siguiente API

Identificación

Solicitud de un token de sesion

Campos de solicitud:

Path Type Description

username

String

el codigo de usuario

password

String

la clave del usuario

Campos de respuesta:

Path Type Description

username

String

el codigo de usuario

roles

Array

Lista de roles

token_type

String

Bearer

access_token

String

token a enviar en cada peticion

expires_in

Number

segundos de validez del token

refresh_token

String

token a utilizar para refrescar el access_token

Ejemplo:

$ echo '{
  "username" : "-747670988@test.com",
  "password" : "password"
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/login' 'Accept:application/json' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:45 GMT
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Content-Length: 216
Server: Jetty(9.2.16.v20160414)

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.....",
  "expires_in" : 3600,
  "refresh_token" : "eyJhbGciOiJIUzI1NiJ9.....",
  "roles" : [ "ROLE_USER" ],
  "token_type" : "Bearer",
  "username" : "-747670988@test.com"
}

Identificación incorrecta

Solicitud de un token de sesion con credenciales inválidas. El sistema devuelve el error 401 Not authorized

Campos de solicitud:

Path Type Description

username

String

el codigo de usuario

password

String

la clave del usuario

Ejemplo:

$ echo '{
  "username" : "-747670988@test.com",
  "password" : "drowssap"
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/login' 'Accept:application/json' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 401 Unauthorized
Date: Wed, 21 Dec 2016 22:13:45 GMT
WWW-Authenticate: Bearer
Server: Jetty(9.2.16.v20160414)

/api/validate

Solicitud de validación de un token de sesion

Campos de solicitud:

No hay. Ojo es necesario envíar el token

Campos de respuesta:

Path Type Description

username

String

el codigo de usuario

roles

Array

Lista de roles

token_type

String

Bearer

access_token

String

token a enviar en cada peticion

expires_in

Number

segundos de validez del token

Ejemplo:

$ http POST 'https://telotraigodemipueblo.herokuapps.com/api/validate' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:46 GMT
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
Content-Length: 167
Server: Jetty(9.2.16.v20160414)

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.....",
  "expires_in" : 3600,
  "roles" : [ "ROLE_USER" ],
  "token_type" : "Bearer",
  "username" : "-747670988@test.com"
}

/api/me

Solicitud del perfil del usuario logeado

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del usuario

nombre

class java.lang.String

el nombre del usuario

username

class java.lang.String

el alias del usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/me' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:50 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 94

{
  "id" : 1585344147578880,
  "nombre" : "1820451322",
  "username" : "1820451322@test.com"
}

APIs gestión

Las APIs de gestión son del estilo CRUD destinadas a que un usuario pueda realizar un mantenimiento mínimo de sus recursos (Lugares, Viajes, Productos, Pedidos, etc)

/api/conoce

Mediante este API la aplicación permite la típica gestión CRUD (alta, baja, modificación, borrado) de los lugares de un usuario.

Alta (POST)

Campos de solicitud:

Path Type Description

nombre

class java.lang.String

el nombre del lugar

latitud

class java.lang.Number

la latitud

longitud

class java.lang.Number

la longitud

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del lugar

nombre

class java.lang.String

el nombre del lugar

latitud

class java.lang.Number

la latitud

longitud

class java.lang.Number

la longitud

recibe

interface java.util.List

una lista de viajes que recibe

tiene

interface java.util.List

una lista de productos que tiene

recibe[]

interface java.util.List

Un array de viajes

tiene[]

interface java.util.List

Un array de productos

usuario.id

class java.lang.String

el id del usuario

usuario.username

class java.lang.String

el codigo de usuario

usuario.nombre

class java.lang.String

el nombre del usuario

Ejemplo:

$ echo '{
  "nombre" : "451192078",
  "latitud" : 1,
  "longitud" : 10
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/conoce' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 201 Created
Date: Wed, 21 Dec 2016 22:14:00 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/api/conoce/1585344235798528
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 232

{
  "id" : "1585344235798528",
  "latitud" : 1.0,
  "longitud" : 10.0,
  "nombre" : "451192078",
  "tiene" : [ ],
  "usuario" : {
    "id" : "1585344224509952",
    "nombre" : "232001255",
    "username" : "232001255@test.com"
  }
}

Listar (GET)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

[]

Array

Un array de lugares

[].id

class java.lang.String

el identificador unico del lugar

[].nombre

class java.lang.String

el nombre del lugar

[].latitud

class java.lang.Number

la latitud

[].longitud

class java.lang.Number

la longitud

[].recibe

interface java.util.List

una lista de viajes que recibe

[].tiene

interface java.util.List

una lista de productos que tiene

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:01 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 236

[ {
  "id" : "1585344235798528",
  "latitud" : 1.0,
  "longitud" : 10.0,
  "nombre" : "451192078",
  "tiene" : [ ],
  "usuario" : {
    "id" : "1585344224509952",
    "nombre" : "232001255",
    "username" : "232001255@test.com"
  }
} ]

Ver (GET + id)

Campos de solicitud:

Table 1. /api/conoce/{id}
Parameter Description

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del lugar

nombre

class java.lang.String

el nombre del lugar

latitud

class java.lang.Number

la latitud

longitud

class java.lang.Number

la longitud

recibe

interface java.util.List

una lista de viajes que recibe

tiene

interface java.util.List

una lista de productos que tiene

usuario.id

class java.lang.String

el id del usuario

usuario.username

class java.lang.String

el codigo de usuario

usuario.nombre

class java.lang.String

el nombre del usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344235798528' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:01 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 232

{
  "id" : "1585344235798528",
  "latitud" : 1.0,
  "longitud" : 10.0,
  "nombre" : "451192078",
  "tiene" : [ ],
  "usuario" : {
    "id" : "1585344224509952",
    "nombre" : "232001255",
    "username" : "232001255@test.com"
  }
}

Actualizar (PUT)

Campos de solicitud:

Table 2. /api/conoce/{id}
Parameter Description

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del lugar

nombre

class java.lang.String

el nombre del lugar

latitud

class java.lang.Number

la latitud

longitud

class java.lang.Number

la longitud

recibe

interface java.util.List

una lista de viajes que recibe

tiene

interface java.util.List

una lista de productos que tiene

usuario.id

class java.lang.String

el id del usuario

usuario.username

class java.lang.String

el codigo de usuario

usuario.nombre

class java.lang.String

el nombre del usuario

Ejemplo:

$ echo '{
  "nombre" : "451192078",
  "latitud" : 100,
  "longitud" : 200
}' | http PUT 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344235798528' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:02 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/api/conoce/1585344235798528
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 235

{
  "id" : "1585344235798528",
  "latitud" : 100.0,
  "longitud" : 200.0,
  "nombre" : "451192078",
  "tiene" : [ ],
  "usuario" : {
    "id" : "1585344224509952",
    "nombre" : "232001255",
    "username" : "232001255@test.com"
  }
}

Borrar (DELETE)

Campos de solicitud:

Table 3. /api/conoce/{id}
Parameter Description

id

el Id del recurso

Campos de respuesta:

No procede. Retorna 204 Not content

Ejemplo:

$ http DELETE 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344235798528' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 204 No Content
Date: Wed, 21 Dec 2016 22:14:02 GMT
X-Application-Context: application:test:0
Server: Jetty(9.2.16.v20160414)

/api/conoce/{lugar}/productos

Mediante este API la aplicación permite la típica gestión CRUD (alta, baja, modificación, borrado) de los productos de un lugar de un usuario.

Alta (POST)

Campos de solicitud:

Path Type Description

texto

class java.lang.String

el nombre del producto

precio

class java.lang.Number

el precio al que lo conseguimos

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del producto

texto

class java.lang.String

un texto que describe el producto

precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ echo '{
  "texto" : "un queso rico",
  "precio" : 10
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344197443584/productos' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 201 Created
Date: Wed, 21 Dec 2016 22:13:57 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/productoRest/show/1585344206995456
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 79

{
  "id" : "1585344206995456",
  "precio" : 10.0,
  "texto" : "un queso rico"
}

Listar (GET)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

[]

Array

Un array de productos

[].id

class java.lang.String

el identificador unico del producto

[].texto

class java.lang.String

un texto que describe el producto

[].precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344197443584/productos' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:57 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 83

[ {
  "id" : "1585344206995456",
  "precio" : 10.0,
  "texto" : "un queso rico"
} ]

Ver (GET + id)

Campos de solicitud:

Table 4. /api/conoce/{idLugar}/productos/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del producto

texto

class java.lang.String

un texto que describe el producto

precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344197443584/productos/1585344206995456' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:58 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 79

{
  "id" : "1585344206995456",
  "precio" : 10.0,
  "texto" : "un queso rico"
}

Actualizar (PUT)

Campos de solicitud:

Table 5. /api/conoce/{idLugar}/productos/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del producto

texto

class java.lang.String

un texto que describe el producto

precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ echo '{
  "texto" : "texto actualizado",
  "precio" : 888
}' | http PUT 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344197443584/productos/1585344206995456' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:58 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/productoRest/show/1585344206995456
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 84

{
  "id" : "1585344206995456",
  "precio" : 888.0,
  "texto" : "texto actualizado"
}

Borrar (DELETE)

Campos de solicitud:

Table 6. /api/conoce/{idLugar}/productos/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

No procede. Retorna 204 Not content

Ejemplo:

$ http DELETE 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344197443584/productos/1585344206995456' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 204 No Content
Date: Wed, 21 Dec 2016 22:13:59 GMT
X-Application-Context: application:test:0
Server: Jetty(9.2.16.v20160414)

/api/conoce/{lugar}/viajes

Mediante este API la aplicación permite la típica gestión CRUD (alta, baja, modificación, borrado) de los viajes de un lugar de un usuario.

Alta (POST)

Campos de solicitud:

Path Type Description

texto

class java.lang.String

una descripcion del viaje

fechatope

class java.util.Date

feha tope para hacer pedidos

vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del viaje

texto

class java.lang.String

un texto que describe el viaje

fechatope

class java.util.Date

feha tope para hacer pedidos

vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Ejemplo:

$ echo '{
  "texto" : "eiii que me voy",
  "fechatope" : 1482617620545,
  "vuelvo" : 1483222420546
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344057581568/viajes' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 201 Created
Date: Wed, 21 Dec 2016 22:13:40 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/viajeRest/show/1585344069541888
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 119

{
  "fechatope" : "2016/12/24",
  "id" : "1585344069541888",
  "texto" : "eiii que me voy",
  "vuelvo" : "2016/12/31"
}

Listar (GET)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

[]

Array

Un array de viajes

[].id

class java.lang.String

el identificador unico del viaje

[].texto

class java.lang.String

un texto que describe el viaje

[].fechatope

class java.util.Date

feha tope para hacer pedidos

[].vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344057581568/viajes' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:41 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 123

[ {
  "fechatope" : "2016/12/24",
  "id" : "1585344069541888",
  "texto" : "eiii que me voy",
  "vuelvo" : "2016/12/31"
} ]

Ver (GET + id)

Campos de solicitud:

Table 7. /api/conoce/{idLugar}/viajes/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del viaje

texto

class java.lang.String

un texto que describe el viaje

fechatope

class java.util.Date

feha tope para hacer pedidos

vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344057581568/viajes/1585344069541888' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:41 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 119

{
  "fechatope" : "2016/12/24",
  "id" : "1585344069541888",
  "texto" : "eiii que me voy",
  "vuelvo" : "2016/12/31"
}

Actualizar (PUT)

Campos de solicitud:

Table 8. /api/conoce/{idLugar}/viajes/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del viaje

texto

class java.lang.String

un texto que describe el viaje

fechatope

class java.util.Date

feha tope para hacer pedidos

vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Ejemplo:

$ echo '{
  "texto" : "texto actualizado"
}' | http PUT 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344057581568/viajes/1585344069541888' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:42 GMT
X-Application-Context: application:test:0
Location: http://localhost:42575/viajeRest/show/1585344069541888
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 121

{
  "fechatope" : "2016/12/24",
  "id" : "1585344069541888",
  "texto" : "texto actualizado",
  "vuelvo" : "2016/12/31"
}

Borrar (DELETE)

Campos de solicitud:

Table 9. /api/conoce/{idLugar}/viajes/{id}
Parameter Description

idLugar

el Id del lugar

id

el Id del recurso

Campos de respuesta:

No procede. Retorna 204 Not content

Ejemplo:

$ http DELETE 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344057581568/viajes/1585344069541888' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 204 No Content
Date: Wed, 21 Dec 2016 22:13:42 GMT
X-Application-Context: application:test:0
Server: Jetty(9.2.16.v20160414)

/api/conoce/{lugar}/viajes/{viaje}/pedidos

Mediante este API la aplicación permite a un usuario ver, aceptar y rechazar los pedidos que otros usuarios le han realizado

Listar (GET)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de pedidos

[].id

class java.lang.String

el identificador unico del pedido

[].cantidad

class java.lang.Integer

la cantidad que deseo pedir

[].producto.id

class java.lang.String

el id del producto pedido

[].solicitante.id

class java.lang.Integer

el id del usuario que lo pide

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344121847808/viajes/1585344121847809/pedidos' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:49 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 160

[ {
  "cantidad" : 2,
  "id" : "1585344133300224",
  "producto" : {
    "id" : "1585344121847810"
  },
  "solicitante" : {
    "id" : "1585344119627776"
  }
} ]

Ver (GET + id)

Campos de solicitud:

Table 10. /api/conoce/{idLugar}/viajes/{idViaje}/pedidos/{id}
Parameter Description

idLugar

el Id del lugar

idViaje

el Id del viaje

id

el Id del recurso

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del pedido

cantidad

class java.lang.Integer

la cantidad que deseo pedir

producto.id

class java.lang.String

el id del producto pedido

solicitante.id

class java.lang.Integer

el id del usuario que lo pide

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344121847808/viajes/1585344121847809/pedidos/1585344133300224' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:49 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 156

{
  "cantidad" : 2,
  "id" : "1585344133300224",
  "producto" : {
    "id" : "1585344121847810"
  },
  "solicitante" : {
    "id" : "1585344119627776"
  }
}

Borrar (DELETE)

Campos de solicitud:

Table 11. /api/conoce/{idLugar}/viajes/{idViaje}/pedidos/{id}
Parameter Description

idLugar

el Id del lugar

idViaje

el Id del viaje

id

el Id del recurso

Campos de respuesta:

no tiene

Ejemplo:

$ http DELETE 'https://telotraigodemipueblo.herokuapps.com/api/conoce/1585344121847808/viajes/1585344121847809/pedidos/1585344133300224' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 204 No Content
Date: Wed, 21 Dec 2016 22:13:49 GMT
X-Application-Context: application:test:0
Server: Jetty(9.2.16.v20160414)

APIs "sociales"

Las APIs "sociales" son aquellas destinadas a interactuar entre dos (o más usuarios) como pueden ser la búsqueda de usuarios, el sistema de mensajería, solicitud de pedido, etc

/api/search

Búsqueda de usuarios por nombre

Obtener un listado de usuarios según un nombre

Campos de solicitud:

Parameter Description

like

Expresión a filtrar

max

maximo de usuarios a recuperar

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de usuarios

[].id

class java.lang.String

el id del usuario

[].nombre

class java.lang.String

el nombre del usuario

[].username

class java.lang.String

el codigo de usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/search/usuario?like=username&max=5' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:54 GMT
X-Application-Context: application:test:0
Content-Language: en
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 3

[ ]

Búsqueda de usuarios por lugares

Obtener un listado de usuarios según el nombre de un lugar

Campos de solicitud:

Parameter Description

like

Expresión a filtrar

max

maximo de usuarios a recuperar

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de usuarios

[].id

class java.lang.String

el id del usuario

[].nombre

class java.lang.String

el nombre del usuario

[].username

class java.lang.String

el codigo de usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/search/lugar?like=almendralejo&max=5' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:55 GMT
X-Application-Context: application:test:0
Content-Language: en
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 3

[ ]

/api/mensajes

El API de mensajería permite a un usuario enviar mensajes a otros usuarios (sean de su red o no) así como ver sus mensajes

Ver mi buzón

Campos de solicitud:

Parameter Description

onlynews

Si true sólo los no leidos

max

maximo mensajes a recuperar

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de mensajes

[].destinatariosid

class java.lang.String

el id del usuario

[].destinatariosnombre

class java.lang.String

el nombre del usuario

[].destinatariosusername

class java.lang.String

el codigo de usuario

[].remitenteid

class java.lang.String

el id del usuario

[].remitentenombre

class java.lang.String

el nombre del usuario

[].remitenteusername

class java.lang.String

el codigo de usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/mensajes?onlynews=false&max=10' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:43 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 267

[ {
  "destinatarios" : [ {
    "id" : "1585344089309184",
    "nombre" : "1786253412",
    "username" : "1786253412@test.com"
  } ],
  "enviado" : "2016-12-21T22:13:43+0000",
  "id" : "1585344093560832",
  "leido" : null,
  "texto" : "hola",
  "tipo" : "MENSAJE"
} ]

/api/invitacion

El API de invitación permite enviar una solicitud de contacto así como aceptar la misma

/api/invitacion/send

Cuando un usuario desea conectar con otro le enviará una solicitud de conexión mediante el API de invitación el cual se resuelve internamente como un mensaje a un usuario de otro usuario.

Campos de solicitud:

Path Type Description

destinatarios

Array

Un array de destinatarios

destinatarios[].id

class java.lang.String

el id del usuario destinatario del mensaje

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del mensaje

tipo

class java.lang.String

el tipo de mensaje (MENSAJE, INVITACION, PEDIDO, …​)

texto

class java.lang.String

el texto del mensaje

enviado

class java.util.Date

la fecha en que fue enviado

leido

class java.util.Date

la fecha en la que fue leido o null si no lo ha sido todavia

destinatarios[]

class ttp.Usuario

un array de usuarios destinatarios

remitente

class ttp.Usuario

el remitente del mensaje

Ejemplo:

$ echo '{
  "destinatarios" : [ {
    "id" : 1585344002433025
  } ]
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/invitacion/send' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 201 Created
Date: Wed, 21 Dec 2016 22:13:34 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 158

{
  "enviado" : "2016-12-21T22:13:35+0000",
  "id" : 1585344024403968,
  "texto" : "Hola, me gustaría que me admitieras en tu red",
  "tipo" : "INVITACION"
}

/api/invitacion/accept

Cuando un usuario desea aceptar la solicitud de contacto lo realizará a través de este API

Campos de solicitud:

Path Type Description

mensaje

class java.lang.String

el id del usuario destinatario del mensaje

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del mensaje

tipo

class java.lang.String

el tipo de mensaje (MENSAJE, INVITACION, PEDIDO, …​)

texto

class java.lang.String

el texto del mensaje

enviado

class java.util.Date

la fecha en que fue enviado

leido

class java.util.Date

la fecha en la que fue leido o null si no lo ha sido todavia

destinatarios[]

class ttp.Usuario

un array de usuarios destinatarios

remitente

class ttp.Usuario

el remitente del mensaje

Ejemplo:

$ echo '{
  "mensaje" : 1585344024403968
}' | http POST 'https://telotraigodemipueblo.herokuapps.com/api/invitacion/accept' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:36 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 342

{
  "destinatarios" : [ {
    "id" : "1585344002433025",
    "nombre" : "-281916135_friend",
    "username" : "-281916135_friend@test.com"
  } ],
  "enviado" : "2016-12-21T22:13:35+0000",
  "id" : 1585344024403968,
  "leido" : "2016-12-21T22:13:36+0000",
  "texto" : "Hola, me gustaría que me admitieras en tu red",
  "tipo" : "INVITACION"
}

/api/lugares

El API de lugares permite a un usuario ver los lugares de su red, es decir, los lugares dados de alta por sus conocidos

Listar (GET)

Campos de solicitud:

Parameter Description

max

maximo lugares a recuperar

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de lugares

[].tiene[]

interface java.util.List

Un array de productos

[].tiene[].id

class java.lang.String

el identificador unico del producto

[].tiene[].texto

class java.lang.String

un texto que describe el producto

[].tiene[].precio

class java.lang.Number

el precio al que se consigue

[].usuario.id

class java.lang.String

el id del usuario

[].usuario.username

class java.lang.String

el codigo de usuario

[].usuario.nombre

class java.lang.String

el nombre del usuario

[].id

class java.lang.String

el identificador unico del lugar

[].nombre

class java.lang.String

el nombre del lugar

[].latitud

class java.lang.Number

la latitud

[].longitud

class java.lang.Number

la longitud

[].recibe

interface java.util.List

una lista de viajes que recibe

[].tiene

interface java.util.List

una lista de productos que tiene

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/lugares?max=10' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:03 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 321

[ {
  "id" : "1585344254779392",
  "latitud" : 2.0,
  "longitud" : 1.0,
  "nombre" : "mi lugar",
  "tiene" : [ {
    "id" : "1585344254779394",
    "precio" : 10.0,
    "texto" : "queso rico"
  } ],
  "usuario" : {
    "id" : "1585344250912768",
    "nombre" : "1705663932",
    "username" : "1705663932@test.com"
  }
} ]

Ver (GET + id)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del lugar

nombre

class java.lang.String

el nombre del lugar

latitud

class java.lang.Number

la latitud

longitud

class java.lang.Number

la longitud

recibe

interface java.util.List

una lista de viajes que recibe

tiene

interface java.util.List

una lista de productos que tiene

tiene[]

interface java.util.List

Un array de productos

tiene[].id

class java.lang.String

el identificador unico del producto

tiene[].texto

class java.lang.String

un texto que describe el producto

tiene[].precio

class java.lang.Number

el precio al que se consigue

usuario.id

class java.lang.String

el id del usuario

usuario.username

class java.lang.String

el codigo de usuario

usuario.nombre

class java.lang.String

el nombre del usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/lugares/1585344254779392' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:04 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 317

{
  "id" : "1585344254779392",
  "latitud" : 2.0,
  "longitud" : 1.0,
  "nombre" : "mi lugar",
  "tiene" : [ {
    "id" : "1585344254779394",
    "precio" : 10.0,
    "texto" : "queso rico"
  } ],
  "usuario" : {
    "id" : "1585344250912768",
    "nombre" : "1705663932",
    "username" : "1705663932@test.com"
  }
}

/api/lugares/{idLugar}/productos

El API de lugares permite a un usuario ver también los productos que un usuario puede traer de un lugar

Listar (GET)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

[]

Array

Un array de productos

[].id

class java.lang.String

el identificador unico del producto

[].texto

class java.lang.String

un texto que describe el producto

[].precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/lugares/1585344254779392/productos' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:04 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 80

[ {
  "id" : "1585344254779394",
  "precio" : 10.0,
  "texto" : "queso rico"
} ]

Ver (GET + id)

Campos de solicitud:

No requiere

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del producto

texto

class java.lang.String

un texto que describe el producto

precio

class java.lang.Number

el precio al que se consigue

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/lugares/1585344254779392/productos/1585344254779394' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:14:05 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 76

{
  "id" : "1585344254779394",
  "precio" : 10.0,
  "texto" : "queso rico"
}

/api/viajes

El API de viajes permite a un usuario ver los viajes de su red, es decir, los viajes programados proximamente de sus conocidos

Listar (GET)

Campos de solicitud:

Parameter Description

max

maximo viajes a recuperar

Campos de respuesta:

Path Type Description

[]

interface java.util.List

Un array de viajes

[].lugar.id

class java.lang.String

el identificador unico del lugar

[].lugar.nombre

class java.lang.String

el nombre del lugar

[].usuario.id

class java.lang.String

el id del usuario

[].usuario.username

class java.lang.String

el codigo de usuario

[].usuario.nombre

class java.lang.String

el nombre del usuario

[].id

class java.lang.String

el identificador unico del viaje

[].texto

class java.lang.String

un texto que describe el viaje

[].fechatope

class java.util.Date

feha tope para hacer pedidos

[].vuelvo

class java.util.Date

fecha en la que vuelve del viaje

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/viajes?max=10' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:52 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 290

[ {
  "fechatope" : "2016/12/24",
  "id" : "1585344163610625",
  "lugar" : {
    "id" : "1585344163610624",
    "nombre" : "mi lugar"
  },
  "texto" : "con la fregoneta",
  "usuario" : {
    "id" : "1585344159719424",
    "username" : "435112269@test.com"
  },
  "vuelvo" : "2016/12/31"
} ]

Ver (GET + id)

Campos de solicitud:

no require

Campos de respuesta:

Path Type Description

id

class java.lang.String

el identificador unico del viaje

texto

class java.lang.String

un texto que describe el viaje

fechatope

class java.util.Date

feha tope para hacer pedidos

vuelvo

class java.util.Date

fecha en la que vuelve del viaje

.lugar.id

class java.lang.String

el identificador unico del lugar

.lugar.nombre

class java.lang.String

el nombre del lugar

.usuario.id

class java.lang.String

el id del usuario

.usuario.username

class java.lang.String

el codigo de usuario

.usuario.nombre

class java.lang.String

el nombre del usuario

Ejemplo:

$ http GET 'https://telotraigodemipueblo.herokuapps.com/api/viajes/1585344163610625' 'Accept:application/json' 'Authorization:Bearer eyJhbGciOiJIUz....' 'Content-Type:application/json; charset=UTF-8'
HTTP/1.1 200 OK
Date: Wed, 21 Dec 2016 22:13:53 GMT
X-Application-Context: application:test:0
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Server: Jetty(9.2.16.v20160414)
Content-Length: 286

{
  "fechatope" : "2016/12/24",
  "id" : "1585344163610625",
  "lugar" : {
    "id" : "1585344163610624",
    "nombre" : "mi lugar"
  },
  "texto" : "con la fregoneta",
  "usuario" : {
    "id" : "1585344159719424",
    "username" : "435112269@test.com"
  },
  "vuelvo" : "2016/12/31"
}

/api/viajes/{id}/pedidos

El API de pedidos permite a un usuario solicitar una cantidad de un producto determinado para que se la traiga en un viaje concreto.

Crear (POST)

Campos de solicitud:

Unresolved directive in network/pedidos.asciidoc - include::/builds/telotraigodemipueblo/api/tfg/telotraigodemipueblo/build/generated-snippets/viajes/pedido/request-fields.adoc[]

Campos de respuesta:

Unresolved directive in network/pedidos.asciidoc - include::/builds/telotraigodemipueblo/api/tfg/telotraigodemipueblo/build/generated-snippets/viajes/pedido/response-fields.adoc[]

Ejemplo:

Unresolved directive in network/pedidos.asciidoc - include::/builds/telotraigodemipueblo/api/tfg/telotraigodemipueblo/build/generated-snippets/viajes/pedido/httpie-request.adoc[]

Unresolved directive in network/pedidos.asciidoc - include::/builds/telotraigodemipueblo/api/tfg/telotraigodemipueblo/build/generated-snippets/viajes/pedido/http-response.adoc[]