Este recurso de aprendizaje es una actividad creada originalmente como caso práctico del proyecto de aprendizaje Dirección y gestión de proyectos y sistemas informáticos.

API Backend: Versión 0.1 y 0.2[editar]

Tecnologías usadas[editar]

Google Cloud Storage (GCS)
1. Utilizado para el almacenamiento de los ficheros.
Google Datastore (GDS)
1. Utilizado para almacenamiento de metadatos de los ficheros.
Google App Engine (GAE)
1. Plataforma en la que se despliega el Backend

Dirección actual del backend[editar]

La API para hacer peticiones al backend de mokap está en la siguiente dirección:

api.mokap.es

El servlet que se encarga de procesar las peticiones se denomina backend. De esta manera, la url completa para hacer peticiones es http://api.mokap.es/backend

Tipos de peticiones[editar]

Actualmente soporta dos tipos de peticiones http:

GET: Para recuperar resultados de búsqueda. Devuelve descriptores de los recursos que hay en el repositorio que incluyen un determinado texto de búsqueda.
POST: Para subir nuevo contenido.

Gestión de API Keys[editar]

Las peticiones tanto GET como POST están protegidas por un sistema de API Keys. De esta manera, el servidor únicamente atiende peticiones que incluyen un determinado API Key de 30 caracteres proporcionado por parámetro. Esto permite, por un lado, proteger el servicio de almacenamiento, y por otro lado, ahorrar recursos de Cloud en caso de que alguna entidad externa al proyecto intentara utilizar el servicio.

El sistema de autorización por API keys está pensado únicamente para su uso entre backends.

En el caso de que el servidor no reciba un api key, o este no sea válido, devolverá siempre como respuesta un código de error 403 (Unauthorized).

El api key se proporciona como parámetro dentro de la petición HTTP, ya sea GET o POST, de la siguiente manera:

url?k=API_KEY

De este modo, cualquier petición GET o POST desde la comunidad de Mokap debería empezar por:

http://api.mokap.es/backend?k=API_KEY

Peticiones GET (v0.1)[editar]

Las peticiones get pueden recibir además dos parámetros adicionales de entrada:

q: Texto a buscar
c: cursor que devuelve app engine para búsquedas paginadas. En caso de que haya más resultados de los que pueden proporcionarse como resultado de un único request, AppEngine devuelve este valor cursor para que en una petición posterior puedan recuperarse la siguiente página de elementos. Lo único que hay que hacer es, en el caso de que el servidor devuelva que hay más elementos totales que los que contiene la respuesta, guardar el valor searchCursor y pasarlo como argumento en el siguiente request, y así sucesivamente hasta haber procesado todos los resultados.

Las peticiones devuelven como resultado un objeto JSON con los siguientes campos:

total: Número total de resultados que contienen el parámetro de búsqueda proporcionado
results: Una lista con los descriptores de cada uno de los elementos incluidos en la respuesta. La estructura de cada descriptor viene especificada por la clase RepoElement: https://github.com/e-ucm/ead/blob/master/build-tools/generators/src/main/resources/schema/editor/components/repo/repoelement.json
No obstante, los campos más importantes son:
- contentsUrl: enlace para generar otra petición GET que recupera un zip con los contenidos del elemento (imágenes, código json para que funcione en mokap, etc)
- thumbnailUrlList: lista con thumbnails disponibles

count: Un entero indicando cuantos elementos de entre los totales se incluyen en la respuesta. Debe ser siempre menor o igual a total. Equivale a results.length.
searchCursor: puntero proporcionado por AppEngine para búsquedas paginadas. Se proporciona únicamente cuando count<total.

Ejemplo de petición get donde se busca por la cadena tree (q=tree):

http://api.mokap.es/backend?k=API_KEY&q=tree

Esto devuelve un resultado parecido al siguiente (v0.1):

"count": 2,

"total": 5,

"searchCursor": "CursorProporcionadoPorAppEngine serializado - suele ser una cadena bastante larga",

"results": [

"libraryId": "freepik_nature_01",

"thumbnailWidthList": [128, 72],

"width": 148.0,

"thumbnailUrlList": ["http://api.mokap.es/download?filename=4836609111359488/thumbnails/128x176.png", "http://api.mokap.es/download?filename=4836609111359488/thumbnails/72x99.png"],

"class": "es.eucm.ead.schema.editor.components.repo.RepoElement",

"licenseName": "link-author",

"contentsUrl": "http://api.mokap.es/download?filename=4836609111359488.zip",

"descriptionI18nList": ["en", "en_EN", "en_US", "en_UK", "es", "es_ES"],

"descriptionList": ["",	"", "",	"", "", ""],

"publisher": "freepik",

"version": 2.014112113E9,

"id": "freepik_nature_019",

"height": 203.0,

"categoryList": ["elements-objects"],

"authorName": "FreePik",

"authorUrl": "http://www.freepik.com/",

"nameI18nList": ["en", "en_EN", "en_US", "en_UK", "es","es_ES"],

"tagList": ["Freepik", "Nature", "Naturaleza", "Cartoon", "Forest", "Bosque"],

"thumbnailHeightList": [176, 99],

"nameList": ["Fruit 3", "Fruit 3", "Fruit 3", "Fruit 3", "Fruta 3", "Fruta 3"],

"entityRef": "4836609111359488"

},

"libraryId": "freepik_nature_01",

"thumbnailWidthList": [128, 256, 512, 72],

"width": 1024.0,

"thumbnailUrlList": ["http://api.mokap.es/download?filename=5167132077719552/thumbnails/128x128.png", "http://api.mokap.es/download?filename=5167132077719552/thumbnails/256x256.png", "http://api.mokap.es/download?filename=5167132077719552/thumbnails/512x512.png", "http://api.mokap.es/download?filename=5167132077719552/thumbnails/72x72.png"],

"class": "es.eucm.ead.schema.editor.components.repo.RepoElement",

"licenseName": "link-author",

"contentsUrl": "http://api.mokap.es/download?filename=5167132077719552.zip",

"descriptionI18nList": ["en", "en_EN", "en_US", "en_UK", "es", "es_ES"],

"descriptionList": ["", "", "", "", "", ""],

"publisher": "freepik",

"version": 2.014112113E9,

"id": "freepik_nature_0189",

"height": 1024.0,

"categoryList": ["elements-objects"],

"authorName": "FreePik",

"authorUrl": "http://www.freepik.com/",

"nameI18nList": ["en", "en_EN", "en_US", "en_UK", "es","es_ES"],

"tagList": ["Freepik", "Nature", "Naturaleza", "Cartoon", "Forest", "Bosque"],

"thumbnailHeightList": [128, 256, 512, 72],

"nameList": ["Tree 64", "Tree 64", "Tree 64", "Tree 64", "Árbol 64", "Árbol 64"],

"entityRef": "5167132077719552"

Peticiones POST[editar]

Para realizar una petición post hay que incluir el fichero a subir (siempre en formato ZIP) en el stream de la conexión. Este zip debe contener tres cosas:

Una carpeta thumbnails con el thumbnail del elemento en distintas resoluciones. Los thumbnails deben ser siempre pngs no entrelazados, con transparencia, codificación de colores RGBA no indexada. La resolución de cada thumbnail se especifica en el nombre del fichero de la siguiente manera: anchoxalto.png
Un fichero contents.zip con el elemento en sí (debe ser autocontenido).
Un fichero descriptor.json con el RepoElement que describe el elemento en el catálogo del repositorio.

Así pues, el fichero a subir debe tener la siguiente estructura (asumiendo que el fichero se llama id_elemento.zip):

id_elemento.zip/

 thumbnails/

               72x72.png

               256x256.png

…

contents.zip
descriptor.json

Cambios de la v0.2:[editar]

Hemos decidido que no tiene sentido recibir una lista de thumbnails en cada petición y para cada elemento por lo que hemos refactorizado la gestión de thumbnails de la siguiente manera:

Peticiones GET (v0.2)[editar]

Se han añadido los siguientes parámetros de entrada:

w: Opcional, Integer, indica al servidor qué anchura te thumbnail esperas que tengan los elementos en la respuesta. Este tamaño es una mera indicación que servirá para que el servidor escoja el thumbnail con la anchura más apropiada según lo que se le ha indicado en este campo para cada elemento.
h: Opcional, Integer, en este caso le indica al servidor la altura del thumbnail esperado en cada elemento.

Ojo pues si el servidor no encuentra un thumbnail con exactamente el tamaño buscado devolverá el que más se acerque, así que no hay que tratar estos parámetros como garantía de que los thumbnails tendrán el tamaño indicado.

Nótese cómo los elementos del repositorio (RepoElement) ahora disponen de un campo adicional thumbnailUrl. Este será el campo de la respuesta que contendrá la dirección del thumbnail elegido por el servidor en función de los campos w y h proporcionados en la petición.

Por ejemplo, un elemento de la petición anterior adaptada a la v0.2 sería:

http://api.mokap.es/backend?k=API_KEY&q=tree&w=500&h=500

Donde obtendremos como respuesta :

{
	"count": 2,
	"total": 5,
	"searchCursor": "CursorProporcionadoPorAppEngine serializado - suele ser una cadena bastante larga",
	"results": [
	{

        "libraryId":"freepik_nature_01",
        "width":1024.0,
        "class":"es.eucm.ead.schema.editor.components.repo.RepoElement",
        "licenseName":"link-author",
        "contentsUrl":"http://api.mokap.es/download?filename=5167132077719552.zip",
        "descriptionI18nList":["en", "en_EN", "en_US", "en_UK", "es", "es_ES"],
        "descriptionList":["", "", "", "", "", ""],
        "publisher":"freepik",
        "version":2.014112113E9,
        "id":"freepik_nature_0189",
        "height":1024.0,
        "contentsSize":0.017704964,
        "categoryList":["elements-objects"],
        "thumbnailUrl":"http://api.mokap.es/download?filename=5167132077719552/thumbnails/512x512.png",
        "authorName":"FreePik",
        "authorUrl":"http://www.freepik.com/",
        "nameI18nList":["en", "en_EN", "en_US", "en_UK", "es", "es_ES"],
        "tagList":["Freepik", "Nature", "Naturaleza", "Cartoon", "Forest", "Bosque"],
        "nameList":["Tree 64", "Tree 64", "Tree 64", "Tree 64", "Árbol 64","Árbol 64"],
        "entityRef":"5167132077719552"
    },

{
		...otros elementos...
	}
	]
}