trabajo fin de grado documentación y ajustes de un api...

Graduado en Ingeniería Informática

Universidad Politécnica de Madrid

Escuela Técnica Superior deIngenieros Informáticos

TRABAJO FIN DE GRADO

Documentación y ajustes de un API REST

Autor: Nicolás Ortiz Suaña

Director: Ángel Herranz Nieva

MADRID, JUNIO DE 2018

ÍndiceÍndice de figuras III

Índice de tablas III

Resumen IV

1. Motivación 1

2. Introducción 3

3. Estado del arte 53.1. Lenguaje de modelado del API . . . . . . . . . . . . . . . . . . . . . . . 5

3.2. Herramienta de generación . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.3. Estado inicial de la documentación en Coowry . . . . . . . . . . . . . . . 9

4. Automatización de la documentación 104.1. Modelado del API mediante RAML . . . . . . . . . . . . . . . . . . . . 10

4.2. Automatización HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4.3. Automatización PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4.4. Entendiendo la transformación. Raml2html . . . . . . . . . . . . . . . . 12

5. Diseño e implementación 155.1. Estructura de la automatización . . . . . . . . . . . . . . . . . . . . . . . 15

5.2. Convenciones en RAML . . . . . . . . . . . . . . . . . . . . . . . . . . 17

5.2.1. Tipos de request y response . . . . . . . . . . . . . . . . . . . . 17

5.2.2. Cambios en los códigos de respuesta . . . . . . . . . . . . . . . . 18

5.2.3. Recursos o subrecursos . . . . . . . . . . . . . . . . . . . . . . . 18

5.2.4. Esquema de seguridad . . . . . . . . . . . . . . . . . . . . . . . 19

5.2.5. Markdown dentro de RAML . . . . . . . . . . . . . . . . . . . . 19

5.2.6. Modularización del modelado . . . . . . . . . . . . . . . . . . . 20

5.3. Proceso de generación . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.3.1. Pestañas de ejemplos . . . . . . . . . . . . . . . . . . . . . . . . 21

5.3.2. Lenguajes mostrados como ejemplo en HTML . . . . . . . . . . 21

5.3.3. Lenguajes mostrados como ejemplo en PDF . . . . . . . . . . . . 27

5.3.4. Estructura de los capítulos . . . . . . . . . . . . . . . . . . . . . 28

5.3.5. Formación de las URIs de los recursos . . . . . . . . . . . . . . . 30

5.3.6. Estilo en HTML . . . . . . . . . . . . . . . . . . . . . . . . . . 31

5.3.7. Problemas con los navegadores . . . . . . . . . . . . . . . . . . 32

5.4. Alcance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

5.5. Metodología de trabajo . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

6. Resultados y conclusiones 34

Bibliografía 36

I

A. Anexo I: Recursos del API 37A.1. Preapprovals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

A.1.1. Preapprovals/{trid} . . . . . . . . . . . . . . . . . . . . . . . . . 37

A.1.2. Preapprovals/{trid}/cancellation . . . . . . . . . . . . . . . . . . 38

A.2. Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

A.3. Trades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

A.3.1. Trades/{trid} . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

A.3.2. Trades/{trid}/authorization . . . . . . . . . . . . . . . . . . . . . 43

A.3.3. Trades/{trid}/cancellation . . . . . . . . . . . . . . . . . . . . . 44

A.3.4. Trades/{trid}/tokens . . . . . . . . . . . . . . . . . . . . . . . . 45

A.4. Numbers/{msisdn} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

A.5. Agents/callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

B. Anexo II: Código 47B.1. Ejemplo de modelización de un recurso RAML . . . . . . . . . . . . . . 47

B.2. Código Nunjucks a HTML (Slate) . . . . . . . . . . . . . . . . . . . . . 55

B.2.1. Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

B.2.2. Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

B.2.3. Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

B.2.4. Hoja de estilo CSS para HTML . . . . . . . . . . . . . . . . . . 70

B.3. Código Nunjucks a PDF (Md) . . . . . . . . . . . . . . . . . . . . . . . 74

B.3.1. Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

B.3.2. Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

II

Índice de figuras1. Esquema general del proceso a conseguir con este proyecto. . . . . . . . 1

2. Esquema del proceso del generador del PDF. . . . . . . . . . . . . . . . 2

3. Esquema del proceso del generador del HTML. . . . . . . . . . . . . . . 2

4. Codificación de parámetros request mediante tipos . . . . . . . . . . . . 6

5. Codificación de un recurso en RAML . . . . . . . . . . . . . . . . . . . . 7

6. Ejemplo de un recurso definido en RAML . . . . . . . . . . . . . . . . . 7

7. Mostrar un recurso mediante Nunjucks . . . . . . . . . . . . . . . . . . . 8

8. Ejemplo de un recurso mostrado mediante Nunjucks . . . . . . . . . . . . 8

9. Página oficial del API de Coowry [1]. . . . . . . . . . . . . . . . . . . . 9

10. Esquema del proceso de compilación para generar los documentos auto-máticamente. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

11. Esquema del proceso de funcionamiento de la herramienta raml2html. . . 13

12. Esquema del diseño de los recursos. . . . . . . . . . . . . . . . . . . . . 18

13. Pestañas de los distintos lenguajes [1]. . . . . . . . . . . . . . . . . . . . 21

14. Ejemplo de petición REST [1]. . . . . . . . . . . . . . . . . . . . . . . . 22

15. Ejemplo de respuesta REST [1]. . . . . . . . . . . . . . . . . . . . . . . 23

16. Ejemplo de petición cURL [1]. . . . . . . . . . . . . . . . . . . . . . . . 24

17. Ejemplo de respuesta cURL [1]. . . . . . . . . . . . . . . . . . . . . . . 25

18. Ejemplo de petición Elixir [1]. . . . . . . . . . . . . . . . . . . . . . . . 26

19. Ejemplo de respuesta Elixir [1]. . . . . . . . . . . . . . . . . . . . . . . 26

20. Ejemplo de respuesta cURL en el PDF. . . . . . . . . . . . . . . . . . . . 27

21. Parte descriptiva del recurso del HTML [1]. . . . . . . . . . . . . . . . . 28

22. Parte de respuestas del recurso del HTML [1]. . . . . . . . . . . . . . . . 28

23. Parte descriptiva del recurso del PDF. . . . . . . . . . . . . . . . . . . . 29

24. Parte de respuestas del recurso del PDF. . . . . . . . . . . . . . . . . . . 30

25. Commits realizados sobre la rama preapprovals to raml [2]. . . . . . . . 33

26. Body request parameters del recurso Preapprovals. . . . . . . . . . . . . 37

27. Body request parameters del recurso Payments. . . . . . . . . . . . . . . 39

28. Body request parameters del recurso Trades. . . . . . . . . . . . . . . . . 42

29. Body request parameters del recurso Trades/trid/authorization. . . . . . . 43

30. Body request parameters del recurso Agents/callbacks. . . . . . . . . . . 46

Índice de tablas1. Relación entre RAML y objetos JavaScript en raml2html . . . . . . . . . 14

III

Resumen

Este trabajo de fin de grado se basa en la documentación del API REST de

Coowry utilizando RAML como lenguaje de modelado del API REST. Dicha

documentación dará lugar al ajuste de la documentación del API actual una

vez realizadas las correcciones oportunas. La documentación permitirá la ge-

neración automática de documentación del API.

Una vez modelado el API REST mediante RAML, y haciendo uso de tem-

plates de Nunjucks, podremos generar de manera automática la documenta-

ción tanto para su visualización en una página web (HTML) como en PDF,

de modo que cualquier cambio en el API REST se realice únicamente en el

modelado en RAML.

Palabras clave: trabajo fin de grado, API REST, Coowry, RAML, Nun-

jucks, HTML, PDF, documentación, automático, clientes.

Abstract

This end-of-grade project is based on the documentation of Coowry REST

API using RAML as modeling language of the REST API. This documen-

tation will lead to the adjustment of current API’s documentation once the

appropriate corrections have been done. The documentation will allow the

automatic generation of API documentation.

Once we have modeled the REST API using RAML, and using Nunjucks

templates, we can automatically generate the documentation both for viewing

on a web page (HTML) and in PDF, so that any change in the REST API is

done only in RAML modeling.

Keywords: end-of-grade project, API REST, Coowry, RAML, Nunjucks,

HTML, PDF, documentation, automatic, clients.

IV

1. MotivaciónLa motivación para realizar esta documentación mediante un lenguaje de modelado

(RAML) es el de automatizar futuras modificaciones o incluir nuevas formas de mostrar

la información del API REST, sin tener que realizar grandes cambios o más de los nece-

sarios. Esto quiere decir, que una vez los templates son implementados, mostrándonos la

información en el momento y en la forma que deseamos, y si el API REST ha sido mode-

lado mediante RAML, ya no nos tendremos que preocupar de nada más, ya que mediante

un proceso automatizado, podremos generar documentación de calidad y personalizable

para los usuarios del API (PDF y HTML).

Esto tiene una ventaja añadida, y es que las modificaciones en el API REST, solo de-

beremos actualizarlas en el modelado RAML y se visualizarán automáticamente los cam-

bios en la documentación (HTML y PDF). Y de la misma forma, si únicamente queremos

cambiar la apariencia de los clientes, deberemos modificar los templates (Nunjucks), de-

jando la documentación del API REST intacta.

El proceso automático que queremos generar es el mostrado en la siguiente figura,

donde los ficheros marcados en azul, son los correspondientes a realizar en este Trabajo

de Fin de Grado.

Figura 1: Esquema general del proceso a conseguir con este proyecto.

Si realizamos una visión con mayor profundidad del proceso Generador, nos encon-

tramos con los procesos mostrados en las siguientes figuras:

1

Figura 2: Esquema del proceso del generador del PDF.

Figura 3: Esquema del proceso del generador del HTML.

2

2. IntroducciónEl trabajo a desarrollar consiste en documentar el API de Coowry, empresa que per-

mite pagar con tu móvil, sin cuentas bancarias, sin tarjetas y sin cuotas. Para ello existen

diferentes fases.

Estas fases consisten en estructurar, limpiar, aclarar, enriquecer y automatizar la in-

formación que proporcionaremos sobre el API. Las fases por las que iremos mejorando y

mostrando esta información serán las siguientes:

Primero, deberemos arreglar, modificar o enriquecer la documentación previa dispo-

nible del API. Ello incluye arreglar posibles fallos ya presentes, añadir o mejorar descrip-

ciones, o enriquecer con nuevos ejemplos.

Después deberemos aportar una documentación más específica de los recursos propios

del API, junto con sus parámetros de petición y sus posibles respuestas, así como ejem-

plos de estos en diferentes lenguajes (REST, cURL, Elixir) mediante el uso de pestañas en

la web. Estos recursos deberán vincularse mediante enlaces dentro de la documentación

anteriormente descrita.

Por último, deberemos ajustar la visualización de la nueva información añadida a la

página de la documentación del API. Esto consta de arreglar ficheros nunjucks (templa-

tes definidos en html, jquery y javascript). Después mediante un template realizado con

Markdown, y el fichero RAML, proporcionaremos también un documento pdf con toda

la información del API.

Por tanto, los objetivos presentes en la realización de la documentación del API son

los siguientes:

Familiarización con RAML y sus herramientas.

Familiarización con el API de Coowry.

Familiarización con HTML, Javascript y JQUERY.

Documentar el API de Coowry en RAML.

Generar documentación de forma automática (PDF y HTML).

Desplegar y ajustar los estilos de la documentación en la web.

Gestionar las fases del trabajo con la herramienta Git.

Documentación propia del trabajo.

El alcance personal de este proyecto es el de conseguir conocimientos en toda posible

herramienta que incluya la documentación de un API, estas son: RAML, HTML, jQuery,

3

javascript, markdown, etc. Y conseguir que mediante un fichero RAML y mediante tem-

plates, se generen cliente web y pdf de manera automática.

4

3. Estado del arteEste apartado se centrará en la explicación de porque se usan las herramientas selec-

cionadas en este trabajo y cuáles son sus ventajas. Debido a que sería complicado elegir

nuevas herramientas, ya que existe bastante trabajo previo, y el uso de nuevas herramien-

tas podría modificar su uso.

Como dato adicional, para el entorno de desarrollo se ha usado Atom, que en este

momento se ha convertido en una gran herramienta gracias a la inclusión de módulos,

lo que ha permitido definir la sintaxis de los múltiples lenguajes usados en este trabajo,

permitiendo desarrollar todo el código en un mismo lugar.

3.1. Lenguaje de modelado del APIPara definir los recursos del API, tarea de este trabajo, se propuso el uso de Swagger

o RAML, pero finalmente se optó por el lenguaje RAML, por su simplicidad (basado en

YAML), pero sobre todo por poseer herramientas en línea con las que se pueden generar

clientes para probar el API y es muy extensible. Esto quiere decir, que gracias a que esta

basado en YAML, podremos generar distintos de documentación, aunque en este caso la

generaremos únicamente para PDF y HTML.

En este momento RAML ha evolucionado de su versión 0.8 a la versión 1.0. Esto nos

permite crear tipos, es decir, podemos definir códigos de respuesta, ejemplos o errores

como tipos, lo que nos permitirá crear un código más modular. En la Figura 4 observamos

como de forma sencilla podemos definir un tipo en RAML.

5

Figura 4: Codificación de parámetros request mediante tipos

A la hora de definir la información de un recurso, RAML nos permite estructurar su

contenido, por lo que nos será más fácil una posible modificación en el futuro. Como

muestra el ejemplo de la Figura6, podemos observar como el recurso /preapprovals se

muestra mediante la codificación en RAML mostrada en la Figura 5.

6

Figura 5: Codificación de un recurso en RAML

Figura 6: Ejemplo de un recurso definido en RAML

7

3.2. Herramienta de generaciónA la hora de desplegar el cliente del API en la web debemos definir el estilo y la in-

formación que se mostrará, para ello hemos optado por usar la herramienta “raml2html”,

ya que es una herramienta muy configurable, y podremos optar a distintos tipos de do-

cumentación, no solo a HTML.“raml2html” mediante Nunjucks consume la información

contenida en el RAML y produce un fichero resultante con la información y el estilo se-

leccionado mediante el fichero Nunjucks.

Este template nos permite definir que mostrar en cada momento, logrando que la ge-

neración del API se lleve a cabo de forma automática. Un ejemplo de ello es como mos-

tramos la información de un recurso de forma limpia y ordenada (Figura 8), con unas

pocas líneas de código (Figura7).

Figura 7: Mostrar un recurso mediante Nunjucks

Figura 8: Ejemplo de un recurso mostrado mediante Nunjucks

8

3.3. Estado inicial de la documentación en CoowryLa documentación del API de Coowry ha pasado por varias fases durante su desa-

rrollo, en un principio, se optó por una documentación más clara pero menos específi-

ca en la que no se definieran los recursos propiamente, si no, una redacción del com-

portamiento del API, esta podría ser descrita mediante HTML puro, mediante mark-

down o mediante LaTeX. Finalmente se describió mediante Markdown. Markdown per-

mite la inclusión de terminología HTML, por lo que podemos definir enlaces o esti-

los dentro de la misma. El resultado lo podemos encontrar ya en el enlace del API:

http://doc.coowry.com/api/Podemos observar el resultado en la Figura 9.

Figura 9: Página oficial del API de Coowry [1].

9

4. Automatización de la documentaciónEn esta sección se describirá como mediante el modelado del API en RAML y algunos

mandatos previamente definidos en un proceso de compilación, podremos automatizar la

generación de la documentación del API, como se muestra en la siguiente figura:

Figura 10: Esquema del proceso de compilación para generar los documentos automáti-camente.

4.1. Modelado del API mediante RAMLAntes de comenzar el modelado deberemos tener en cuenta la estructura interna de

nuestro API, que se resume en el Anexo 1 de esta documentación. Para poder modelar el

API dispondremos de anotaciones en RAML. Estas son las siguientes:

title: proporciona el título del API.

version: proporciona la versión del API.

baseUri: proporciona la URI base del API.

protocols: proporciona el protocolo del API.

securedBy: proporciona la seguridad ofrecida por el API.

10

securitySchemes: proporciona los esquemas de seguridad ofrecidos por el API.

madiaType: proporciona el tipo de los objetos de petición y respuesta del API.

description: proporciona una descripción sobre la anotación en la que nos encon-

tremos.

types: proporciona esquema de anotaciones sobre un tipo.

type: proporciona el tipo de la anotación (string, integer, boolean, ...), puede ser un

type definido por nosotros mismos en types.

required: proporciona el requerimiento de una anotación (true, false).

/{nombre del recurso}: proporciona el nombre de un recurso del API, o subrecurso

si se encuentra indexado.

Algunas de estas anotaciones las podremos encontrar también indexadas dentro de

otra anotación (description, mediaType, type, ...). Sirven para definir la estructura general

del API, pero disponemos de más anotaciones internas para los recursos, aparte de las

anteriormente mencionadas que se pueden indexar dentro de otras anotaciones, estas son

las siguientes:

displayName: proporciona el nombre del recurso.

{tipo del método}: proporciona el método (POST, GET) del recurso.

body: a continuación de esta anotación se define el cuerpo.

example: proporciona el ejemplo de request o response del recurso.

responses: proporciona los códigos de respuesta (200, 400, 404, ...) del recurso.

Mediante todas las anotaciones anteriores podemos definir toda la estructura y ele-

mentos del API. El código RAML del modelado del API de Coowry se encuentra en el

Anexo 2.

4.2. Automatización HTMLA partir del template nunjucks (Slate) que vamos a generar en este proyecto y median-

te la herramienta raml2html podremos definir cuándo y cómo se mostrará la información

contenida en nuestro fichero RAML, que contiene toda la información del API, propor-

cionándonos un fichero HTML automáticamente.

Mediante nuestra codificación en Nunjucks (Slate), cuyo código se adjunta en el

Anexo 2, accederemos a los recursos mediante un árbol de sintaxis abstracto (AST), que

describiremos en una sección posterior, para generar el HTML correspondiente.

11

4.3. Automatización PDFA partir del template nunjucks (Md) que vamos a generar en este proyecto y median-

te las herramientas raml2html y pandoc podremos definir cuándo y cómo se mostrará la

información contenida en nuestro fichero RAML, que contiene toda la información del

API, proporcionándonos un fichero PDF automáticamente.

Mediante nuestra codificación en Nunjucks (Md), cuyo código se adjunta en el Anexo2, accederemos a los recursos mediante un árbol de sintaxis abstracto (AST), que des-

cribiremos en una sección posterior, y mediante una herramienta de LaTeX, Pandoc, que

transforma nuestro nunjucks, junto a las anotaciones Markdown, generaremos el PDF co-

rrespondiente.

4.4. Entendiendo la transformación. Raml2htmlComo hemos visto en la Figura 10 es necesaria la herramienta raml2html para el pro-

ceso de automatización que estamos buscando. La herramienta raml2html funciona de la

siguiente forma. Primero realiza un parsing del fichero RAML que contiene la modeli-

zación del API, con lo que genera un árbol de sintaxis abstracto (AST) que contiene la

instanciación de los objetos, en lenguaje JavaScript, que forman el API. Después median-

te un proceso de rendering descrito por los templates que hemos generado, en los que se

accede a los objetos del árbol de sintaxis abstracto, se creara un fichero HTML o Mark-

down (fichero intermedio). El esquema del proceso de funcionamiento de la herramienta

raml2html, se muestra en la siguiente figura:

12

Figura 11: Esquema del proceso de funcionamiento de la herramienta raml2html.

En la siguiente página se muestra la Tabla 1, que describe el árbol de traducción de

RAML a Nunjucks:

13

RAML AST raml2htmlValor Anotación AccesoRecurso /{resource name}: resources[i]

Subrecurso /{subresource name}: resources[i].resources[i]

Métodos get: o post: resources[i].methods[i]

Tipo del método resources[i].methods[i].methods[i]

Nombre del recurso displayName: resources[i].displayName

Descripción del recurso description: resources[i].description

Descripción del método description: resources[i].methods[i].description

URI del recurso resources[i].relativeUri

URI del padre del recurso resources[i].parentUrl

Parámetros del URI del recur-

so

resources[i].allUriParameters[i]

Número de parámetros de la

URI del recurso

resources[i].allUriParameters.length

Nombre del parámetro de la

URI del recurso

displayName: resources[i].allUriParameters[i].displayName

Descripción del parámetro de

la URI del recurso

description: resources[i].allUriParameters[i].description

Parámetros del QueryPara-

meters del recurso

resources[i].methods[i].queryParameters[i]

Número de parámetros del

QueryParameters del recurso

resources[i].methods[i].queryParameters.length

Nombre del parámetro del

QueryParameters del recurso

displayName: resources[i].methods[i].queryParameters[i].displayName

Descripción del parámetro

del QueryParameters del re-

curso

description: resources[i].methods[i].queryParameters[i].description

Parámetros request del recur-

so

resources[i].methods[i].body[0].properties[i]

Número de parámetros re-

quest del recurso

resources[i].methods[i].body[0].properties.length

Nombre del parámetro del re-

quest del recurso

displayName: resources[i].methods[i].body[0].properties[i].displayName

Descripción del parámetro

del request del recurso

description: resources[i].methods[i].body[0].properties[i].description

Requerimiento del parámetro

del request del recurso

required: resources[i].methods[i].body[0].properties[i].required

Ejemplos del request del re-

curso

example: resources[i].methods[i].body[0].examples[i].value

Respuestas del método del re-

curso

responses: resources[i].method[i].responses[i]

Clave (Número) de la res-

puesta del método del recurso

resources[i].method[i].responses[i].key

Nombre de la respuesta del

método del recurso

displayName: resources[i].method[i].responses[i].body[0].displayName

Descripción de la respuesta

del método del recurso

description: resources[i].method[i].responses[i].body[0].description

Ejemplo de la respuesta del

método del recurso

example: resources[i].method[i].responses[i].body[0].examples[i].value

Tabla 1: Relación entre RAML y objetos JavaScript en raml2html

14

5. Diseño e implementaciónEn esta sección se describirán las decisiones que se llevaron a cabo durante la realiza-

ción de este Trabajo de Fin de Grado.

5.1. Estructura de la automatizaciónComo se comentó en la sección 4 de este documento, en este caso se ha decidido optar

por crear un Makefile para orquestar la traducción, en el que primero se instalan las he-

rramientas necesarias, después se carga los ficheros (hoja de estilos, templates nunjucks,

modelado RAML), a continuación se describen las opciones de la herramienta raml2html,tales como la versión a utilizar, y con esto generaremos el fichero correspondiente (HTML

o PDF).

En el mismo Makefile describimos la automatización del PDF, llamando a pandoc que

convertirá el fichero en Markdown también generado por raml2html en un fichero LaTeX,

que usará la herramienta pdflatex para generar el PDF mediante el código LaTeX. El es-

quema de este Makefile lo podemos ver en la Figura 10.

El código de este Makefile lo podemos ver a continuación:

1 # TODO: refactor2 # - use variable with target dependencies (templates,

docs, examples, schemas, images,...)3 # - use variable with all targets (html, md, pdf, ...)4 # - use automatic variables5 NODE_MODULES=../node_modules6 RAML2HTML=$(NODE_MODULES)/.bin/raml2html7 COMMON=../common8

9 # S3 bucket for deployment10 DOCS3BUCKET = doc.coowry.com11

12 usage:13 @echo USAGE:14 @echo " make all"15 @echo " make tooling # Prepare tooling: raml2html"16

17 all: coowry_integration_guide_v2.htmlcoowry_integration_guide_v2-main.pdf

18

19 # Setup the tooling20 tooling:

15

21 npm install --prefix ../ \22 [email protected] \23 [email protected] \24 [email protected]

26 %.html: %.raml docs/* images/* $(COMMON)/templates/coowry-logo-s.svg $(COMMON)/templates/_variables_coowry.styl$(COMMON)/templates/slate_* Makefile

27 cp $(COMMON)/templates/slate_index.nunjucks $(NODE_MODULES)/raml2html-slate-theme/templates/index.nunjucks

28 cp $(COMMON)/templates/slate_resource.nunjucks $(NODE_MODULES)/raml2html-slate-theme/templates/resource.nunjucks

29 cp $(COMMON)/templates/slate_root.nunjucks $(NODE_MODULES)/raml2html-slate-theme/templates/root.nunjucks

30 # Markdown generation31 $(RAML2HTML) \32 --theme raml2html-slate-theme \33 --logo $(COMMON)/templates/coowry-logo-s.svg \34 --color-theme $(COMMON)/templates/_variables_coowry.

styl \35 -i $< -o $@36

37 %-main.pdf: %-main.tex %.ltx coowryapi.sty38 pdflatex $<39 pdflatex $<40

41 %.ltx: %.md42 pandoc --top-level-division=chapter --listings -t latex $

< -o $@43 # sed ’s/0\.05/0.25/g’ -i $@ # for some reason pandoc

generates 0.05\columnwidth columns in tables44

45 %.md: %.raml Makefile docs/* images/* $(COMMON)/templates/md_*

46 # Hacking until we prepare our own theme for Markdown (oriented to LaTeX generation with pandoc)

47 cp $(COMMON)/templates/md_index.nunjucks $(NODE_MODULES)/raml2html-markdown-theme/index.nunjucks

48 cp $(COMMON)/templates/md_resource.nunjucks $(NODE_MODULES)/raml2html-markdown-theme/resource.nunjucks

49 # Markdown generation

16

50 $(RAML2HTML) --theme raml2html-markdown-theme -i $< -o $@51

52 # Upload the site53 upload: coowry_integration_guide_v2.html54 # Upload mkdocs site55 aws s3 cp $< s3://$(DOCS3BUCKET)/api/index.html --acl

public-read --cache-control "public, max-age=86400" --region eu-central-1

56

57

58 clean:59 rm -f *.pdf *.html *.ltx *.md *.aux *.log *.out *.toc60

61 .PRECIOUS: %.ltx %.md62

63 .PHONY: all tooling themes

5.2. Convenciones en RAMLEn esta sección se trataran casos de decisión y diseño referentes a RAML.

5.2.1. Tipos de request y response

A la hora de definir los request y responses de cada recurso, se optó por definir tipos

para cada uno, por ejemplo v2__agent__post__request__trades, ya que cada código de

respuesta puede ser de varios tipos, por ejemplo, puede existir una respuesta 412 mer-chant__not__trusted o 412 value__not__valid.

De esta forma nos encontraremos con tres clases de types:

Los types generados por los request, que serán de la forma v2__agent__{tipo delmétodo}__request__{nombre del recurso/subrecurso}.

Los types generados por los argumentos de los responses, que serán de la forma

v2__agent__response__arguments__{tipo de la respuesta}__{nombre del recurso/-subrecurso}.

Los types generados por los responses, que serán de la forma v2__agent__{tipo delmétodo}__response__{tipo de la respuesta}__{nombre del recurso/subrecurso}.

17

5.2.2. Cambios en los códigos de respuesta

Cuando se modeló el API era necesario definir en algunos recursos varios códigos de

respuesta con la misma clave, esto quiere decir que, por ejemplo, se necesitaban devolver

dos respuestas 412 distintas, esto suponía una limitación para RAML, ya que solo permite

una por recurso. De esta manera se optó por definir los códigos de respuesta 400 y 412,

que eran los que se repetían, como la sucesión de 460 y 470 respectivamente.

Esto es, por ejemplo, si tenemos los códigos de respuesta 412 value_not_valid y 412

merchant_not_trusted, en RAML los definiremos como los códigos de respuesta 470 y

471, aunque internamente los modificaremos para mostrar el correspondiente código, en

este caso 470 y 471 se traducirían por 412 y 412.

5.2.3. Recursos o subrecursos

Cuando se modelaba el API en RAML se tenía que optar por definir los recursos

dentro de otros recursos como subrecursos o como recursos aparte, un ejemplo es es el

siguiente, del recurso /preapprovals obtenemos los recursos /preapprovals/{trid} o /preap-provals/{trid}/authorization, y estos podríamos indexarlos dentro de /preapprovals o co-

mo recursos enteros con su URI completa.

Finalmente, se eligió definir cada recurso y dentro de él cada método o subrecurso, y

de la misma forma dentro de cada subrecurso, sus propios métodos o subrecursos.

Un esquema del diseño se muestra en la siguiente figura:

Figura 12: Esquema del diseño de los recursos.

18

5.2.4. Esquema de seguridad

Dentro del fichero RAML podemos definir la seguridad con la que trabaja el API,

para ello debemos definir cada esquema de seguridad que deseemos utilizar, en este caso

únicamente Basic Authentication, que definimos mediante la anotación securitySchemes.

Una vez definidos los esquemas, debemos seleccionar cual utilizamos mediante la anota-

ción securedBy. El siguiente código es el utilizado para este API:

1 securedBy: [basic]2 securitySchemes:3 basic:4 description: |5 This API supports Basic Authentication.6 type: Basic Authentication

5.2.5. Markdown dentro de RAML

Cuando se comenzó con este trabajo, existía una documentación previa, en la que se

explicaba el API de una forma descriptiva, esta documentación se decidió añadir junto

con los recursos descritos más específicamente mediante el modelado en RAML. Como

RAML acepta anotaciones en Markdown, tales como los utilizados en el recurso /trades:

1 v2__agent__post__request__trades:2 properties:3 sender:4 type: string5 description: |6 **Synchronous payment/Settlments** -> Your API

Key. Provided by Coowry.<br/> **Asynchronous payment** -> The customer’sMSISDN. In international format, eg.+34616839172 or +6212345678910.

7 required: true8 receiver:9 type: string

10 description: |11 **Asynchronous payment** -> Your API Key.

Provided by Coowry.<br/> **Synchronouspayment/Settlment** -> The customer’s MSISDN.In international format, eg. +34616839172 or+6212345678910.

12 required: true

19

se decidió añadir directamente la documentación previa escrita en Markdown mediante la

siguiente anotación en RAML:

1 documentation:2 - title: API Overview3 content: !include docs/api_overview.md4 - title: Payments Overview5 content: !include docs/payments_overview.md6 - title: Trusted Payments7 content: !include docs/trusted_payments.md8 - title: Synchronous Payments9 content: !include docs/sync_payments.md

10 - title: Asynchronous Payments11 content: !include docs/async_payments.md12 - title: Settlements13 content: !include docs/settlements.md14 - title: Callbacks15 content: !include docs/callbacks.md

5.2.6. Modularización del modelado

Aunque en el Anexo 2 de esta documentación se adjunta el fichero RAML como único,

éste esta dividido en 7 ficheros RAML, ya que uno será el maestro que llamará al resto

con la forma:

1 types:2 !include raml_files/raml_types.raml

y el resto complementan al maestro, estos ficheros están divididos en:

Un fichero dedicado a los tipos creados por nosotros mismos, esto incluye el tipo

de request y response al igual que los tipos argument.

Un fichero por cada recurso disponible en el API (/preapprovals, /payments, /trades,

/numbers/msisdn y /agents/callbacks).

20

5.3. Proceso de generaciónEn esta sección se trataran casos de decisión y diseño referentes al proceso de genera-

ción.

5.3.1. Pestañas de ejemplos

A la hora de mostrar los ejemplos, se decidió configurar una pestaña por cada lenguaje

(REST, Elixir, cURL). Cuando se selecciona una pestaña de las mostradas en la Figura13 se muestra el ejemplo del lenguaje en cuestión.

En esta pantalla se mostrarán ejemplos para el request y los responses de cada recurso

o subrecurso.

Figura 13: Pestañas de los distintos lenguajes [1].

5.3.2. Lenguajes mostrados como ejemplo en HTML

En cuanto a los lenguajes mostrados como ejemplo en las peticiones y respuestas del

API, se escogió mostrar tres tipos: la propia llamada REST, mandatos cURL y mandatos

Elixir.

21

REST: Las peticiones y respuestas REST muestran el protocolo HTTP utilizado,

la URI sobre la que se realiza y el json implicado en la petición o en la respuesta,

en las dos siguientes figuras se muestran un ejemplo de petición y otro de respuesta

REST y los códigos utilizados para cada uno.

1 <div class="languagebox rest">2 <pre>3 Example request {{ resource.parentUrl }}{{ resource.

relativeUri }} {{ method.method | upper}}:4

5 {{method.protocols}} {{ (method.method | upper )}} {{response.code}} {{baseUri}}{{resource.parentUrl}}{{resource.relativeUri}}

6 Content-Type: {{body.key}}7

8 <code>{{ example.value }}</code>9 </pre>

10 </div>

Figura 14: Ejemplo de petición REST [1].

1 <div class="languagebox rest">2 <pre>3 Example response {{ respkey }} {{ response.body[0].

displayName }}:4

5 {{method.protocols}} {{ (method.method | upper )}} {{respkey }} {% if (method.method == "get") and (

22

resource.relativeUri == "/trades2") %}{{baseUri}}/trades{% elif (method.method == "get") and (resource.relativeUri == "/trades3") %}{{baseUri}}/trades{%elif (method.method == "get") and (resource.parentUrl == "/trades2") %}{{baseUri}}/trades/{trid}{% else %}{% endif %}

6 Content-Type: {{body.key}}7 <code>{{ example.value }}</code>8 </pre>9 </div>

Figura 15: Ejemplo de respuesta REST [1].

cURL: Las peticiones y respuestas cURL muestran el mandato a utilizar y el json

implicado en la petición, y en la respuesta solamente el json implicado, en las dos

siguientes figuras se muestran un ejemplo de petición y otro de respuesta cURL y

los códigos utilizados para cada uno.

1 <div class="languagebox curl">2 <pre>3 Example curl request {{ resource.parentUrl }}{{

resource.relativeUri }} {{ method.method | upper}}:4

23

5 <code class="bash" >$ curl -u $PUBLICKEY:$PRIVATEKEY -H"Content-Type: application/json" -X {{ method.method | upper}} -d ’</code>

6 <code class="json">{{ example.value }}</code>7 ’ {{baseUri}}{{ resource.parentUrl }}{{ resource.

relativeUri }}8 </pre>9 </div>

Figura 16: Ejemplo de petición cURL [1].

1 <div class="languagebox curl">2 <pre>3 Example curl response {{ respkey }} {{ response.body

[0].displayName }}:4

5 <code>{{ example.value }}</code>6 </pre>7 </div>

24

Figura 17: Ejemplo de respuesta cURL [1].

Elixir: Las peticiones y respuestas Elixir muestran el mandato a utilizar y el json

implicado en la petición, y en la respuesta solamente el json implicado, en las dos

siguientes figuras se muestran un ejemplo de petición y otro de respuesta Elixir y

los códigos utilizados para cada uno.

1 <div class="languagebox elixir">2 <pre>3 Example elixir request {{ resource.parentUrl }}{{

resource.relativeUri }} {{ method.method | upper}}:4

5 <code>:httpc.request(:{{ method.method | upper}},6 { {{baseUri}}{{ resource.parentUrl }}{{ resource.

relativeUri }},[7 {{ example.value }}8 ], ’application/json’, cfd }, [], [])</code>9 </pre>

10 </div>

25

Figura 18: Ejemplo de petición Elixir [1].

1 <div class="languagebox elixir">2 <pre>3 Example elixir response {{ respkey }} {{ response.body


5 <code>{{ example.value }}</code>6 </pre>7 </div>

Figura 19: Ejemplo de respuesta Elixir [1].

26

5.3.3. Lenguajes mostrados como ejemplo en PDF

En cuanto a los lenguajes mostrados en el PDF, la decisión es más complicada, ya que

no se pueden mostrar los tres lenguajes, porque deberían mostrarse en el mismo sitio a la

vez (al contrario que en el HTML, que se pueden mostrar por separado), esto lleva a tener

que elegir un lenguaje como el prioritario para mostrar, y ya que los json involucrados

serán los mismos para todos los lenguajes, se decidió mostrar el lenguaje cURL, ya que

sus mandatos lo hacen más informativo. Un ejemplo se encuentra en la siguiente figura .

1 #### Sample Response2

3 ‘‘‘4 {{ example.value }}5 ‘‘‘

Figura 20: Ejemplo de respuesta cURL en el PDF.

27

5.3.4. Estructura de los capítulos

A la hora de estructurar los capítulos hay que diferenciar entre el HTML y el PDF.

Por el lado del HTML, todos los recursos se encuentran dentro del capítulo Resources,

y dentro de este capítulo los subcapítulos seguirán la indexación tratada en la Figura 12.

En cada capítulo podemos diferenciar entre la parte descriptiva junto con el request y su

ejemplo y la parte de los responses, en donde cada respuesta se diferencia por una línea

horizontal que lo separa del anterior. En las siguientes dos figuras podemos diferenciar

las dos partes.

Figura 21: Parte descriptiva del recurso del HTML [1].

Figura 22: Parte de respuestas del recurso del HTML [1].

28

Por parte del PDF, cada recurso es un capítulo (no existe anidamiento a la hora de

mostrar los resursos), aunque siguen el mismo anidamiento que el mostrado en el es-

quema de la Figura 12. Al igual que en el HTML, también podremos diferenciar entre

parte descriptiva y respuestas, aunque esta vez separadas por subcapítulos. Un ejemplo se

muestra en las siguientes figuras.

Figura 23: Parte descriptiva del recurso del PDF.

29

Figura 24: Parte de respuestas del recurso del PDF.

5.3.5. Formación de las URIs de los recursos

A la hora de acceder a los elementos de los recursos, era necesario especificar una

URI para el elemento en concreto, ya que las URIs no son formadas automáticamente

en el template, y es necesario definir en el identificador de la etiqueta del elemento en

cuestión una URI especifica.

Para definir estas URIs se usó la forma: {baseUri}/resources/{nombre del recurso ósubrecurso}/{tipo de método}.

30

Un ejemplo, sería la siguiente URI: {baseUri}/resources/preapprovals/{trid}/get que

accede al método get dentro del subrecurso /preapprovals/trid.

5.3.6. Estilo en HTML

No solo en el fichero Nunjucks referente al HTML (slate) modifica la apariencia del

HTML final, también mediante la hoja de estilos se puede modificar su apariencia, me-

diante el siguiente código Less, que ha sido especificado para Coowry, modificamos pe-

queñas apariencias en cuanto a los encabezados y los márgenes, usando el código descrito

a continuación:

1 $aside-warning-bg = #ffc5102

3 .tocify-wrapper > img4 max-width: 65%5 margin: 20px auto;6

7 header8 padding: 0 34px9 margin-right: 45%

10 margin-top: 2.5em;11 margin-bottom: 0.8em;12

13 section14 padding-left: 505 px15

16 pre code17 white-space: pre-wrap18

19 // Do not use standard HTML link style20 @css {21 a {22 text-decoration: none;23 }24 a:link, a:visited {25 color: #2d92c8;26

27 }28 a:active {29 color: #ffc51030 }31 }

31

5.3.7. Problemas con los navegadores

Durante el desarrollo del trabajo aparecieron una serie de problemas, tales como pro-

blemas con la seguridad en el navegador Safari, esto suponía únicamente habilitar las

opciones de desarrollador dentro del propio navegador.

Aunque existía otro problema más grave y que costó más descubrir, la apariencia de

los ejemplos, los cuales al no tener espacio suficiente para mostrar el carácter en una

línea, lo cortaba pero dejaba un espacio en blanco al final de la línea, lo cual dificulta-

ría en un futuro la tarea del desarrollador, ya que al copiar el mandato directamente de

la web, el carácter en blanco aparecería, y no funcionaría, por lo cual se optó por añadir

el siguiente mandato dentro de la hoja de estilo, para que el carácter blanco desapareciese.

1 pre code2 white-space: pre-wrap

5.4. AlcanceEl API de Coowry incluye más recursos aparte de los presentados en este trabajo, la

mayor parte han sido tratados aquí, pero hay otros recursos específicos de otras partes de

Coowry (People, Merchant, Operator).

Aquí solo hemos tratado los recursos propios de Merchant (los necesarios para un

agente). Pero en un futuro se pueden añadir estos recursos de una forma simple, única-

mente añadiéndolos al fichero RAML, modelando previamente estos recursos, ya que el

aspecto ha sido tratado para cualquier recurso dentro de los ficheros Nunjucks.

5.5. Metodología de trabajoA fin de llevar un control exhaustivo y de no perder ninguna de las versiones por las

que ha ido pasando el proyecto, se decidió trabajar sobre Git, en este caso sobre BitBuc-

ket, en el repositorio de Coowry, cwapidoc, sobre una nueva rama, preapprovals to raml,en la que se guardarían cada una de las versiones por las que ha pasado el proyecto me-

diante commits a la misma rama.

Esto facilitó el trabajo en paralelo con el resto de compañeros y simplicidad en arre-

glos posteriores, en los que fue necesario volver a una versión anterior, e inclusive a llevar

una versión actualizada por si alguno de los compañeros o el tutor del proyecto necesita-

ba acceder o modificar, dándose el caso, de modificar el logo mostrado en el HTML. En

este caso, el tutor lo modificó y tan solo con un pull se podía estar sincronizado de nuevo

con el resto del grupo. En la siguiente figura se muestra parte de los commits realizados

durante el proyecto en los que podemos apreciar el trabajo en paralelo, en este caso con

32

el tutor.

Figura 25: Commits realizados sobre la rama preapprovals to raml [2].

33

6. Resultados y conclusionesComo resultado final de este Trabajo de Fin de Grado se ha conseguido el objetivo

principal del proyecto, que era el de generar documentación automáticamente del API de

Coowry con calidad y personalizable, también se han conseguido objetivos adicionales

que surgieron durante el desarrollo del mismo, estos son, mostrar distintos lenguajes de

forma selectiva (pestañas) en la página web del API y conseguir una documentación en

PDF adaptada, diferente a la mostrada en la página web.

También se ha conseguido que el contenido (RAML) y la visualización de este (Nun-

jucks) se codifique de manera independiente, y de esta forma permitir cambios por sepa-

rado tanto de contenido como de visualización.

Hay que añadir que algún objetivo adicional no se ha logrado, aunque el objetivo

principal y la gran mayoría sí, como se comentó en el capítulo 5.4 Alcance, será necesa-

rio añadir los recursos restantes, aunque los principales se encuentran disponibles, y esto

solo será necesario añadirlo a la parte de contenido (RAML), ya que la visualización ya

ha sido tratada de manera general para todos los recursos en el fichero Nunjucks, lo que

simplificara la tarea. Además a finales de Julio se entregara a los clientes reales de Co-

owry, por lo que ya es posible su uso.

Como conclusión general del proyecto se puede comprender la importancia de la ge-

neración automática de este tipo de documentaciones, ya que se trata de un gran volumen

de información y quererla mostrar de la manera más simplificada y sencilla posible re-

queriría mucho trabajo, al tratarse de varios recursos, sin embargo, de esta forma solo

es necesario haber construido nuestros propios templates, y una vez hecho esto solo será

necesario añadir la información al modelado del API para que aparezca siempre de la

forma que deseemos. Hay que añadir también la versatilidad que se ha adquirido, ya que

ahora se genera de forma automática para HTML y PDF pero solo realizando un template

podríamos generar un tipo de fichero nuevo.

De este Trabajo de Fin de Grado, como conclusión personal, he obtenido un gran co-

nocimiento en cuanto al tratamiento de macros (Makefile), y aún más conocimiento en

documentar un API mediante un modelado (RAML). Incluso he conseguido adquirir co-

nocimientos propios de Front-end, necesarios para desarrollar el template para la parte de

HTML. En mi paso por el Grado no había desarrollado mucha preparación en este campo,

y casi todo lo que he tratado ha sido Back-end, lo cuál considero un gran aporte personal

al haber ampliado dichos conocimientos.

Las asignaturas dentro del Grado que me han ayudado en gran medida en la realiza-

ción de este Trabajo de Fin de Grado son Sistemas Orientados a Servicios, la cual me

ha ayudado en cuanto a las comunicaciones y estructuras REST, todas las asignaturas en

las que se ha desarrollado mi técnica de programación, tales como Estructura de Compu-

tadores, Programación, Concurrencia, Estructuras de Datos, etc. La asignatura de Web

34

Semántica con su uso de la herramienta de GitHub, me ha proporcionado el conocimiento

necesario para poder utilizarla en la gestión de mi propio proyecto y dentro del repositorio

de Coowry. Y finalmente, Ingeniería del Software II me ha aportado valores en cuanto a

la gestión de un proyecto software que me han facilitado bastante esta tarea durante el

desarrollo de este trabajo.

Como trabajo a futuro queda por realizar la modelización de los recursos restantes, ya

comentada, y generar la modelización para un nuevo API de Coowry basado en aplica-

ciones (Android, IOS, WebApps, Bots, . . . ).

35

Bibliografía[1] Coowry, “Página oficial del api de coowry.” http://doc.coowry.com/api/,

2018. Online; accessed: 9th April 2018.

[2] Bitbucket, “Gestión del trabajo.” https://bitbucket.org, 2018. Online; ac-

cessed: 9th April 2018.

[3] Raml2html, “Especificación de raml2html.” https://github.com/raml2html/raml2html, 2018. Online; accessed: 9th April 2018.

[4] Nunjucks, “Especificación de nunjucks.” https://mozilla.github.io/nunjucks/templating.html, 2018. Online; accessed: 9th April 2018.

[5] Jinja, “Especificación de jinja.” http://jinja.pocoo.org/docs/2.10/templates/, 2018. Online; accessed: 10th May 2018.

[6] Coowry, “Página oficial de coowry.” https://www.coowry.com/, 2018. On-

line; accessed: 9th April 2018.

[7] RAML, “Especificación de raml.” https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/, 2018.

Online; accessed: 9th April 2018.

[8] J. Duckett, “Html and css design and build websites.” Wiley book, 2015.

[9] J. Duckett, “Javascript and jquery.” Wiley book, 2015.

[10] Haxx, “Tutorial de curl.” https://curl.haxx.se/docs/httpscripting.html, 2018. Online; accessed: 9th April 2018.

[11] Rogerdudler, “Manejo rápido de git.” http://rogerdudler.github.io/git-guide/index.es.html, 2018. Online; accessed: 9th April 2018.

[12] w3schools, “Lenguajes propios de programación front.” https://www.w3schools.com, 2018. Online; accessed: 9th April 2018.

[13] ETSIINF, “Recomendaciones sobre el contenido de la memoria final.” https://www.fi.upm.es/?pagina=1475, 2018. Online; accessed: 9th April 2018.

36

A. Anexo I: Recursos del APIEn este anexo comentaré los recursos y sub-recursos de los que dispone el API REST

actual de Coowry de manera resumida, y de esta forma disponer de una visión global del

API de Coowry.

A.1. PreapprovalsPreapprovals enable you to directly bill your customers.Body request parameters are

the following:

Figura 26: Body request parameters del recurso Preapprovals.

Making a POST create a new preapproval. Redirect the user. If she accepts the preap-

proval you woll be able to bill her directly (using /payments).

Possible responses:

200 ok

400 bad request

401 not authorized

412 merchant not trusted

Sub-resources of Preapprovals are the following:

A.1.1. Preapprovals/{trid}

You can check on a customer’s preapproval status by making a call to the /preappro-

vals resource. This is convenient since customers can cancel their preapproval of your

payments at any given time.

37

You need a URI parameter, :trid.

Make a GET request to /preapprovals/:id, where :id is the preapproval id. This will

return the customer’s preapproval status. The body of the request must be left empty and

the request must be authenticated by HTTP Basic Auth using your API key and secret.

Possible responses:

200 ok

401 not authorized

404 not found

A.1.2. Preapprovals/{trid}/cancellation

You can use the preapprovals/:id/cancellation to cancel one of your customers preap-

provals at any time. This is useful you want to allow customers to cancel their preappro-

vals directly from your service. Please note that once cancelled, preapprovals cannot be

reactivated. If you want to regian the customer’s preapproval, you must repeat the process.

You need a URI parameter, :trid.

Making a POST to the /preapprovals/:id/cancellation resource, where :id is the preap-

proval id, will cancel the preapproval.

Possible responses:

204 no content

401 not authorized

404 not found

412 preapproval not active

A.2. PaymentsTo charge a customer, make a POST request to the /payments resource with the cus-

tomer’s preapproval id and the value to be charged.Body request parameters are the follo-

wing:

38

Figura 27: Body request parameters del recurso Payments.

Possible responses:

200 ok

400 bad request

400 value not valid

401 not authorized

412 merchant not trusted

412 preapproval not found

412 sender not billed

412 sender not enough balance

412 net not active

412 sender backlisted

39

A.3. TradesTo charge a customer, make a POST request to the /payments resource with the cus-

tomer’s preapproval id and the value to be charged.Body request parameters are the follo-

wing:

40

Figura 28: Body request parameters del recurso Trades.

Possible responses:

200 ok

400 bad request

400 value not valid

401 not authorized

403 forbidden

404 not found

412 sender unidentified

412 sender net not member


412 net not active

412 too many p2b request

412 sender backlisted

Sub-resources of Trades are the following:

42

A.3.1. Trades/{trid}

If you prefer, you can poll for the result synchronously instead of waiting for a call-

back. You can retrieve the status of a transaction by performing a GET over the /trades re-

source.

You need a URI parameter, :trid. (transaction identifier)

To check the status of a transaction, simply make a GET request to /trades/:id, where

:id is the transaction Id returned when ordering the payment. The body must be left empty.

Possible responses:

200 ok



412 cancelled

412 token timeout

A.3.2. Trades/{trid}/authorization

After you succesfully request a payment from a user, Coowry will send a security co-

de to the user via SMS. You must present the user with a form to enter this code (usually

a 4-digit token) and the terms of service. Once the user enters the token, you must send it

to the API to authorize the trade and complete the payment.

You need a URI parameter, :trid. (transaction identifier)

Figura 29: Body request parameters del recurso Trades/trid/authorization.

The trade is authorized by making a POST to https://api.coowry.com/v2/trades/:trid/authorization

where trid is the trade id returned after requesting the payment.

Possible responses:

43

200 ok

400 bad request

401 not authorized

403 forbidden

404 not found

412 wrong token


412 too many auth attempts

412 wrong status


A.3.3. Trades/{trid}/cancellation

A payment can be cancelled before it is authorized. This is a convenient feature and

you should give the customer the possibility to cancel the payment.

The trade is cancelled by making a POST request to https://api.coowry.com/v2/trades/:trid/cancellation

where trid is the trade id returned after requesting the payment. The body of the request

must be left empty and be encoded in application/json. The Content-Type header should

be set accordingly.

Possible responses:

200 ok

400 bad request

401 not authorized

403 forbidden

404 not found

412 wrong status

44

A.3.4. Trades/{trid}/tokens

You can force the resend of an authorization SMS, which contains the security code

to authorize a trade. This is useful in cases when the SMS is not delivered or the customer

can’t find it. The authorization SMS can be resent a maximum of three times. Please note

that the the security code changes every time the SMS is resent.

The authorization SMS is resent by making a POST request to https://api.coowry.com/v2/trades/:trid/

to where trid is the trade id returned after requesting the payment. The body of the request

must be left empty and be encoded in application/json. The Content-Type header should

be set accordingly.

Possible responses:

204 no content

400 bad request

401 not authorized

403 forbidden

404 not found

412 wrong status

A.4. Numbers/{msisdn}To know what the topup values are for a customer, make a GET request over /num-

bers/:msisdn, where :msisdn is the customer’s phone number.

You need a URI parameter, :msisdn.

A GET request over /numbers/:msisdn will return the available topup values for the

phone number :msisdn, along with some other information. The body must be left empty

and the MSISDN must be in international format. As with all other calls to the API, the

request must be authenticated by HTTP Basic Auth using your API key and secret.

Possible responses:

200 ok

412 sender unidentified

45

A.5. Agents/callbacksCoowry will make callbacks to a URI of your choice to notify you of certain events

(eg. payment confirmation, customer preapproval, and so on). All callbacks are made to

a single URI that you can change at any time, and are signed so you can verify their aut-

henticity. Call- backs consist of POST requests with a pre-defined format to which your

servers must reply with a HTTP status codes 200 OK or 204 No Content.

Figura 30: Body request parameters del recurso Agents/callbacks.

To set or change your callback URI, you must make a POST request to /agents/call-

backs.

Possible responses:

200 ok

404 no content

46

B. Anexo II: Código

B.1. Ejemplo de modelización de un recurso RAMLSe mostrara únicamente la implementación del recurso /preapprovals, ya que el có-

digo completo en RAML ocupará demasiado, y el resto de recursos se implementa de la

misma forma.

1 #%RAML 1.02 title: Merchant Integration3 version: v24 baseUri: https://api.coowry.com/v25 protocols: HTTPS6 securedBy: [basic]7 securitySchemes:8 basic:9 description: |

10 This API supports Basic Authentication.11 type: Basic Authentication12 mediaType: application/json13 description: |14 This guide describes the integration with the two main

flows available to merchants in Coowry: Payments andSettlements.

15 If you are a **developer**, we recommend you use theonline version of this documentation, which is morefriendly and constantly updated. You will find it at [https://api.coowry.com/doc](https://api.coowry.com/doc).

16

17 # Jason reponse types18

19 # There are more than one response in some code response,the real code of the response is

20 # in description of the response. Codes between 460 to 470are differents responses of 400 code,

21 # codes in 470 and later are responses of 412 code.22

23 types:24 #REQUEST25

26 #Request to preapprovals27

28 v2__agent__post__request__preapprovals:29 properties:

47

30 success_url:31 type: string32 description: URL of the success.33 required: true34 failure_url:35 type: string36 description: URL to the failure.37 required: true38 reference:39 type: string40 description: Reference code of the operation.41 required: true42 concept:43 type: string44 description: The concept of the preapproval.45 required: true46

47 # Success response (200) to preapprovals post48

49 v2__agent__post__response__success__preapprovals:50 displayName: ok51 description: If your request was successful, the API will

return a JSON object.52 properties:53 id:54 type: string55 description: The preapproval id.56 required: true57 redirect_url:58 type: string59 description: The URL to which the customer must be

redirected to complete the preapproval process.60 required: true61

62 # Success response (200) to preapprovals get63

64 v2__agent__get__response__success__preapprovals:65 displayName: ok66 description: Make a GET request to /preapprovals/:id,

where :id is the preapproval id. This will return thecustomer’s preapproval status.

67 properties:68 id:69 type: string

48

70 description: The preapproval id.71 required: true72 reference:73 type: string74 description: Provided when creating the preapproval.75 required: true76 active:77 type: boolean78 description: Provided when creating the preapproval.79 required: true80 concept:81 type: string82 description: true if the customer’s preapproval is

still active, false otherwise.83 required: true84

85 # Failure response 40186

87 v2__agent__response__failure__not__authorized:88 displayName: not_authorized89 description: Your credentials are wrong.90 properties:91 status:92 type: integer93 description: Error code.94 required: false95 type:96 type: string97 description: Error type.98 required: false99 description:

100 type: string101 description: A short description of the error.102 required: false103 arguments:104 type:

v2__agent__response__arguments__failure__not__authorized

105 description: Failure arguments included.106 required: false107


110 v2__agent__response__failure__not__found:

49

111 displayName: not_found112 description: Resource not found. Check

the request URL.113 properties:114 status:115 type: integer116 description: Error code.117 required: false118 type:119 type: string120 description: Error type.121 required: false122 description:123 type: string124 description: A short description of

the error.125 required: false126 arguments:127 type:

v2__agent__response__arguments__failure__not__fo

128 description: Failure argumentsincluded.

129 required: false130


133 v2__agent__response__failure__merchant__not__trusted:134 displayName: merchant_not_trusted135 description: You are not verified as a trusted

merchant and cannot use the trustedpayments flow.

136 properties:137 status:138 type: integer139 description: Error code.140 required: false141 type:142 type: string143 description: Error type.144 required: false145 description:146 type: string147 description: A short description of the

50

error.148 required: false149 arguments:150 type:

v2__agent__response__arguments__failure__merchant__no

151 description: Failure arguments included.152 required: false153

154

155 # Resources156

157 /preapprovals:158 displayName: Preapprovals159 description: Preapprovals enable you to directly bill

your customers.160 post:161 description: Creates a **new preapproval**. Redirect

the user. If she accepts the preapproval you woll beable to bill her directly (using ‘/payments‘).

162 body:163 application/json:164 type: v2__agent__post__request__preapprovals165 example: {166 "success_url": "https://mycompany.com/foo

",167 "failure_url": "https://mycompany.com/bar

",168 "reference": "REF-123456789",169 "concept": "Preapproval for shop payments

"170 }171 responses:172 200:173 body:174 application/json:175 type:

v2__agent__post__response__success__preapprovals

176 example: {177 "id": "RdeIQOaQEPUf",178 "redirect_url": "https://pay.coowry.com/

RdeIQOaQEPUf"179 }

51

180 400:181 body:182 application/json:183 type: v2__agent__response__failure__bad__request184 example: {185 "status": 400,186 "type": "bad_request",187 "description": "Error in request

parameters",188 "arguments": {189 "non_valid":[],190 "missing":["sender"],191 "unexpected":[]192 }193 }194 401:195 body:196 application/json:197 type:

v2__agent__response__failure__not__authorized198 example: {199 "status": 401,200 "type": "not_authorized",201 "description": "Unauthorized",202 "arguments": {}203 }204 412:205 body:206 application/json:207 type:

v2__agent__response__failure__merchant__not__trusted

208

209 /{trid}:210 displayName: Preapproval211 description: You can check on a customer’s preapproval

status by making a call to the /preapprovalsresource. This is convenient since customers cancancel their preapproval of your payments at anygiven time.

212 get:213 description: Make a GET request to /preapprovals/:id,

where :id is the preapproval id. This will returnthe customer’s preapproval status. The body of

52

the request must be left empty and the requestmust be authenticated by HTTP Basic Auth usingyour API key and secret.

214 body:215 application/json:216 example: {217 }218 responses:219 200:220 body:221 application/json:222 type:

v2__agent__get__response__success__preapprovals

223 example: {224 "id": "RdeIQOaQEPUf",225 "reference": "REF-12345678",226 "active": false,227 "concept": "Preapproval for shop

payments"228 }229 401:230 body:231 application/json:232 type:

v2__agent__response__failure__not__authorized

233 example: {234 "status": 401,235 "type": "not_authorized",236 "description": "Unauthorized",237 "arguments": {}238 }239 404:240 body:241 application/json:242 type:

v2__agent__response__failure__not__found243 example: {244 "status": 404,245 "type": "not_found",246 "description": "Resource not found"

,247 "arguments": {}

53

248 }249 /cancellation:250 displayName: Preapproval cancellations251 description: You can use the preapprovals/:id/

cancellation to cancel one of your customerspreapprovals at any time. This is useful you wantto allow customers to cancel their preapprovalsdirectly from your service. Please note that oncecancelled, preapprovals cannot be reactivated. Ifyou want to regian the customer’s preapproval, youmust repeat the process.

252 post:253 description: Making a POST to the /preapprovals/:id

/cancellation resource, where :id is thepreapproval id, will cancel the preapproval.

254 body:255 application/json:256 example: {257 }258 responses:259 204:260 body:261 application/json:262 type:

v2__agent__response__success__no__content

263 example: {264 }265 401:266 body:267 application/json:268 type:

v2__agent__response__failure__not__authorized

269 example: {270 "status": 401,271 "type": "not_authorized",272 "description": "Unauthorized",273 "arguments": {}274 }275 404:276 body:277 application/json:278 type:

54

v2__agent__response__failure__not__found279 example: {280 "status": 404,281 "type": "not_found",282 "description": "Resource not found"

,283 "arguments": {}284 }285 412:286 body:287 application/json:288 type:

v2__agent__response__failure__preapproval__not__activ

289 example: {290 "status": 412,291 "type": "preapproval_not_active",292 "description": "The given

preapproval is not active",293 "arguments": {294 "id":"GaDBJPHbVeZR"295 }296 }

B.2. Código Nunjucks a HTML (Slate)B.2.1. Root

1 <!doctype html>2 <html>3 <head>4 <meta charset="utf-8"/>5 <meta content="IE=edge,chrome=1" http-equiv="X-UA-

Compatible"/>6 <meta name="viewport" content="width=device-width,

initial-scale=1, maximum-scale=1"/>7 <title>{{ title }} Documentation</title>8

9 <style type="text/css">{{ css }}</style>10

11 {% include "./js/lib/highlight.min.js.nunjucks" %}12 <script>hljs.initHighlightingOnLoad();</script>13 {% include "./js/lib/jquery.min.js.nunjucks" %}14 {% include "./js/lib/energize.js.nunjucks" %}

55

15 {% include "./js/lib/imagesloaded.min.js.nunjucks" %}16 {% include "./js/lib/jquery_ui.js.nunjucks" %}17 {% include "./js/lib/jquery.highlight.js.nunjucks" %}18 {% include "./js/lib/jquery.tocify.js.nunjucks" %}19 {% include "./js/lib/lunr.js.nunjucks" %}20 {% include "./js/script.js.nunjucks" %}21

22

23 {#Tabs that we have to show on webpage, it must beincluded in this array#}

24 {% set languageTabs = ["rest","curl","elixir"] %}25 {% if languageTabs %}26 <script>27 $(function() {28 setupLanguages({{ languageTabs | dump }});29 });30 </script>31 {% endif %}32

33 <script>34 (function(i,s,o,g,r,a,m){i[’GoogleAnalyticsObject’]=r;i[r

]=i[r]||function(){35 (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();

a=s.createElement(o),36 m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.

parentNode.insertBefore(a,m)37 })(window,document,’script’,’https://www.google-analytics

.com/analytics.js’,’ga’);38

39 ga(’create’, ’UA-46089551-4’, ’auto’);40 ga(’send’, ’pageview’);41

42 </script>43 </head>44

45 <body class="">46 {#There must be a function for each tab, like next#}47 <script>48 function rest() {49 document.querySelectorAll(".language, .elixir").

hidden=true;50 document.querySelectorAll(".language, .curl").

hidden=true;

56

51 document.querySelectorAll(".language, .rest").hidden=false;

52 }53 function curl() {54 document.querySelectorAll(".language, .elixir").

hidden=true;55 document.querySelectorAll(".language, .curl").

hidden=false;56 document.querySelectorAll(".language, .rest").

hidden=true;57 }58 function elixir() {59 document.querySelectorAll(".language, .elixir").

hidden=false;60 document.querySelectorAll(".language, .curl").

hidden=true;61 document.querySelectorAll(".language, .rest").

hidden=true;62 }63 </script>64 <a href="#" id="nav-button">65 <span>66 NAV67 <img src=’data:image/png;base64,

iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAAAAABWESUoAAAAAnRSTlMAAHaTz+AAAAAElFTkSuQmCC’ alt="navbar"/>

68 </span>69 </a>70 <div class="tocify-wrapper">71 <img src=’data:{{ logoMime }};base64,{{ logo }}’ alt

=’logo’ />72 {% if languageTabs %}73 <div class="lang-selector">74 {#Tabs that we have to show on webpage, it must

be included here too#}75 <a href="" onclick="rest()" data-language-

name="rest">rest</a>76 <a href="" onclick="curl()" data-language-

name="curl">curl</a>77 <a href="" onclick="elixir()" data-language-

name="elixir">elixir</a>78 </div>79 {% endif %}80 {% if search %}

57

81 <div class="search">82 <input type="text" class="search" id="input-

search" placeholder="Search">83 </div>84 <ul class="search-results"></ul>85 {% endif %}86 <div id="toc">87 </div>88 </div>89 <div class="page-wrapper">90 <div class="content">91 {% include "./index.nunjucks" %}92 </div>93 <div class="dark-box">94 {% if languageTabs %}95 <div class="lang-selector">96 {#Tabs that we have to show on webpage, it must

be included here too#}97 <a href="" onclick="rest()" data-language-

name="rest">rest</a>98 <a href="" onclick="curl()" data-language-

name="curl">curl</a>99 <a href="" onclick="elixir()" data-language-

name="elixir">elixir</a>100 </div>101 {% endif %}102 </div>103 </div>104 </body>105 </html>

B.2.2. Index

1 {% set comma = joiner() %}2

3 {#------------------------------------------------------------------ #}

4 {# Documentation starts here #}5

6 <h1 id="{{ title | lower | replace(’ ’, ’-’) }}">{{ title}} Documentation</h1>

7 <p>8 {% if version %}<strong>version</strong> {{ version }}<br

/>{% endif %}

58

9 {% if baseUri %}<strong>baseUri</strong> {{ baseUri }}<br/>{% endif %}

10 {% if protocols %}11 <strong>protocols</strong>12 {% for protocol in protocols -%}13 {{ comma() }} {{protocol}}14 {%- endfor %}15 <br/>16 {% endif -%}17 {% if mediaType %}<strong>mediaType</strong> {{

mediaType }}{% endif %}<br/>18 {% for indice in securedBy.length | dump %}19 {% if securedBy %}<strong>securedBy</strong> {{

securitySchemes[securedBy[indice-1].schemeName].type}}{% endif %}

20 {% endfor %}21 </p>22

23 {% for item in documentation %}24 <h1 id="{{ item.title | lower | replace(’ ’, ’-’) }}">{{

item.title }}</h1>25 {% markdown %}26 {{ item.content }}27 {% endmarkdown %}28 {% endfor %}29

30 {# ------------------------------------------------------------------ #}

31 {# Resources start here #}32

33 <h1 id="resources" style="font-size: 350%">Resources</h1>34

35 {% set level = 2 %}36

37 {% for resource in resources %}38 {% include "./resource.nunjucks" %}39 {% endfor %}

B.2.3. Resource

1 {% set level = level + 1 %}2

3 {# Macro needed to change responses keys 460 and so on to400 and 470 and so on to 412 #}

59

4 {% macro changeK(controlKey) %}{%if ((controlKey<470) and (controlKey>459))%}400{%elif controlKey>469 %}412{% else%}{{controlKey}}{% endif %}{% endmacro %}

5

6

7 {#Converting to a good URI. We have to set non recognizedcharacters like / to a recognized one #}

8

9 {% if resource.parentUrl %}10 {% set identificador = "/resources/"+resource.parentUrl.

replace("/","") %}11 {% set identificador = identificador+resource.relativeUri

%}12 {% set identificador = identificador.replace("/","-") %}13 {% set identificador = identificador.replace("-","/") %}14 {% set identificador = identificador.replace("-","/") %}15 {% else %}16 {% set identificador = resource.relativeUri.replace("/",

"-") %}17 {% set identificador = identificador.replace("-","",1)

%}18 {% set identificador = identificador.replace("-","/") %}19 {% set identificador = identificador.replace("/","-") %}20 {% set identificador = identificador.replace("-","/") %}21 {% set identificador = "/resources/"+identificador %}22 {% endif %}23

24 <h{{level}} id="{{ identificador }}" style="font-size: 200%">

25 {% if resource.displayName %}26 {{ resource.displayName }}27 {% endif %}28 <code>{{resource.parentUrl}}{{ resource.relativeUri }}</

code>29 </h{{level}}>30

31 <p>32 {% markdown -%}33 {{ resource.description }}34 {% endmarkdown %}35 </p>36

37 {% if (resource.methods or (resource.description andresource.parentUrl)) %}

60

38 {% for method in resource.methods %}39

40

41 <h{{level+1}} id="{{ identificador }}/{{ method.method }}"style="font-size: 150%">

42 {{ method.method | upper }}43 </h{{level+1}}>44

45 <p>46 <code>{{ (method.method | upper )}}: {{ resource.

parentUrl }}{{ resource.relativeUri }}</code> {% ifmethod.securedBy %} <em>(secured)</em>{% endif %}

47 </p>48

49 {% markdown -%}50

51 <p>{{ method.description }}</p>52

53 {% endmarkdown %}54

55

56 {% for body in method.body %}57

58 {% for example in body.examples %}59

60 {% if method.body[0].properties.length > 0 %}61

62

63 <header style="font-size: 125%"><strong>Bodyrequest parameters</strong></header>

64

65

66 {#Each tab is defined by this, div class="languagebox Tab"#}

67 <div class="languagebox rest">68 {#Be careful with identationt, inside <pre>, the

result html is like code(" " and "/n,/t, andso on" are taking in account)#}

69 <pre>70 Example request {{ resource.parentUrl }}{{ resource.


72 {{method.protocols}} {{ (method.method | upper )}} {{response.code}} {{baseUri}}{{resource.parentUrl}}{{

61

resource.relativeUri}}73 Content-Type: {{body.key}}74

75 <code>{{ example.value }}</code>76 </pre>77 </div>78

79 <div class="languagebox curl">80 {#Be careful with identationt, inside <pre>, the result

html is like code(" " and "/n,/t, and so on" are takingin account)#}

81 <pre>82 Example curl request {{ resource.parentUrl }}{{ resource.


84 <code class="bash" >$ curl -u $PUBLICKEY:$PRIVATEKEY -H "Content-Type: application/json" -X {{ method.method |upper}} -d ’</code>

85 <code class="json">{{ example.value }}</code>86 ’ {{baseUri}}{{ resource.parentUrl }}{{ resource.

relativeUri }}87 </pre>88 </div>89

90 <div class="languagebox elixir">91 <pre>92 Example elixir request {{ resource.parentUrl }}{{ resource.



relativeUri }},[96 {{ example.value }}97 ], ’application/json’, cfd }, [], [])</code>98 </pre>99 </div>

100

101 </br>102 <br/>103 <table>104 <thead>105 <th>Parameter</th>106 <th>Description</th>107 </thead>

62

108 <tbody>109 {% for param in method.body[0].properties %}110 <tr>111 <td>112 <div align="right"><code>{{ param.

displayName }}</code></div>113 <div align="right"><em>{{param.type}}</em>

(<em>{% if param.required == true %}required{% else %}optional{% endif %}</em>)</div>

114 </td>115 <td> {% markdown -%} {{ param.description}}

{% endmarkdown -%} </td>116 </tr>117 {% endfor %}118 </tbody>119 </table>120

121 {% else %}122

123 <div class="languagebox rest">124 <pre>125 Example request {{ resource.parentUrl }}{{ resource.


127 {{method.protocols}} {{ (method.method | upper )}} {{response.code}} {{baseUri}}{{resource.parentUrl}}{{resource.relativeUri}}

128 Content-Type: {{body.key}}129


134 <div class="languagebox curl">135 {#Be careful with identationt, inside <pre>, the


136 <pre>137 Example curl request {{ resource.parentUrl }}{{ resource.


139 <code class="bash">$ curl -u $PUBLICKEY:$PRIVATEKEY -H "Content-Type: application/json" -X {{ method.method |

63

upper}} -d ’</code>140 <code class="json">{{ example.value }}</code>141 ’ {{baseUri}}{{ resource.parentUrl }}{{ resource.

relativeUri }}142 </pre>143 </div>144

145 <div class="languagebox elixir">146 <pre>147 Example elixir request {{ resource.parentUrl }}{{ resource.



relativeUri }},[151 {{ example.value }}152 ], ’application/json’, cfd }, [], [])</code>153 </pre>154 </div>155

156 {% endif %}157

158 {% endfor %}159 {% endfor %}160

161 {% if method.allUriParameters.length != 0 %}162

163

164 <header style="font-size: 125%"><strong>URI Parameters</strong></header>

165 <table>166 <thead>167 <th>Parameter</th>168 <th>Description</th>169 </thead>170 <tbody>171 {% for param in method.allUriParameters %}172 <tr>173 <td>174 <div align="right"><code>{{ param.displayName

}}</code></div>175 <div align="right"><em>{{param.type}}</em> (<em

>{% if param.required == true %}required{%else %}optional{% endif %}</em>)</div>

64

176 </td>177 <td>{{ param.description }}</td>178 </tr>179 {% endfor %}180 </tbody>181 </table>182

183

184 {% endif %}185

186 {% if (method.headers | length) != 0 %}187

188

189 <header style="font-size: 125%"><strong>HeaderParameters</strong></header>

190 <table>191 <thead>192 <th>Parameter</th>193 <th>Description</th>194 </thead>195 <tbody>196 {% for param in method.headers %}197 <tr>198 <td>199 <div align="right"><code>{{ param.displayName




208

209 {% endif %}210

211 {% if (method.queryParameters | length) != 0 %}212

213

214 <header style="font-size: 125%"><strong>QueryParameters</strong></header>

65

215 <table>216 <thead>217 <th>Parameter</th>218 <th>Description</th>219 </thead>220 <tbody>221 {% for param in method.queryParameters %}222 <tr>223 <td>224 <div align="right"><code>{{ param.displayName




233

234 {% endif %}235

236 {% if ((method.responses | length) != 0) %}237

238 <header style="font-size: 150%"><strong>PossibleResponses</strong></header>

239

240 {% for response in method.responses %}241

242 {# Here we save the real key of the response (460.. ->400 & 470.. -> 412) #}

243 {%set controlKey = response.key%}244

245 {% for body in response.body %}246

247 <header style="font-size: 125%" align="center"><hr/><strong><em>Response {{response.body[0].displayName}}</em></strong></header>

248

249 {% for example in response.body[0].examples %}250

251 <div class="languagebox rest">

66

252 <pre>253 Example response {{changeK(controlKey)}} {{ response.body


255 {{method.protocols}} {{ (method.method | upper )}} {{changeK(controlKey)}} {% if (method.method == "get") and(resource.relativeUri == "/trades2") %}{{baseUri}}/trades{% elif (method.method == "get") and (resource.relativeUri == "/trades3") %}{{baseUri}}/trades{% elif (method.method == "get") and (resource.parentUrl == "/trades2") %}{{baseUri}}/trades/{trid}{% else %}{% endif%}

256 Content-Type: {{body.key}}257 <code>{{ example.value }}</code>258 </pre>259 </div>260

261 <div class="languagebox curl">262 {#Be careful with identationt, inside <pre>, the


263 <pre>264 Example curl response {{changeK(controlKey)}} {{ response.

body[0].displayName }}:265


270 <div class="languagebox elixir">271 <pre>272 Example elixir response {{changeK(controlKey)}} {{ response

.body[0].displayName }}:273


278

279 {% endfor %}280

281 <br/>282

283 <table>

67

284 <thead>285 <th>Code</th>286 <th>Type</th>287 <th>Description</th>288 </thead>289 <tbody>290 <tr>291 <td>{{changeK(controlKey)}}</td>292 <td><em>{{response.body[0].displayName}}</

em></td>293 <td>{{response.body[0].description}}</td>294 </tr>295 </tbody>296 </table>297

298 {% if response.body[0].properties.length > 0 %}299

300 <header style="font-size: 115%"><strong>Bodyresponse parameters</strong></header>

301

302 {% endif %}303

304 {%for param in response.body[0].properties%}305

306 <table>307 <thead>308 <th>Parameter</th>309 <th>Description</th>310 </thead>311 <tbody>312 <tr>313 <td>314 <div align="right"><code>{{ param.

displayName }}</code></div>315 <div align="right"><em>{{param.type

}}</em> (<em>{% if param.required== true %}required{% else %}optional{% endif %}</em>)</div>

316 </td>317 <td>{{ param.description }}</td>318 </tr>319 </tbody>320 </table>321

68

322 {% if param.displayName == "arguments" %}323

324 {% if param.properties.length > 0 %}325

326 <header style="font-size: 105%"><strong>Argument parameters</strong></header>

327

328 {%for param2 in param.properties%}329

330 <table>331 <thead>332 <th>Parameter</th>333 <th>Description</th>334 </thead>335 <tbody>336 <tr>337 <td>338 <div align="right"><code>{{

param2.displayName }}</code></div>

339 <div align="right"><em>{{param2.type}}</em> (<em>{% if param2.required == true %}required{%else %}optional{% endif %}</em>)</div>

340 </td>341 <td>{{ param2.description }}</td>342 </tr>343 </tbody>344 </table>345

346 {%endfor%}347 {% endif %}348

349 {%endif%}350

351 {%endfor%}352

353 {%endfor%}354 {%endfor%}355

356 {%endif%}357 {%endfor%}358 {%endif%}

69

359

360 {% for resource in resource.resources %}361 {% include "./resource.nunjucks" %}362 {% endfor %}363 {% set level = level - 1 %}

B.2.4. Hoja de estilo CSS para HTML

1 /*2 Copyright 2008-2013 Concur Technologies, Inc.3

4 Licensed under the Apache License, Version 2.0 (the "License"); you may

5 not use this file except in compliance with the License.You may obtain

6 a copy of the License at7

8 http://www.apache.org/licenses/LICENSE-2.09

10 Unless required by applicable law or agreed to in writing,software

11 distributed under the License is distributed on an "AS IS"BASIS, WITHOUT

12 WARRANTIES OR CONDITIONS OF ANY KIND, either express orimplied. See the

13 License for the specific language governing permissions andlimitations

14 under the License.15 */16

17 ////////////////////18 // BACKGROUND COLORS19 ////////////////////20 $nav-bg = #FAFCFC21 $examples-bg = #2D313422 $dark-box-bg = #2D313423 $code-bg = #272B2D24 $code-annotation-bg = #2D313425 $nav-subitem-bg = transparent26 $nav-active-bg = transparent27 $lang-select-border = transparent28 $lang-select-bg = #24272929

30 // feel free to change this to blue or something

70

31 $lang-select-active-bg = #2d92c832

33 // color of language tab bg when mouse is pressed34 $lang-select-pressed-bg = #2d92c835

36 $main-bg = #FFFFFF37 $aside-notice-bg = #bfe8ff38 $aside-warning-bg = #c97a7e39 $aside-success-bg = #6ac17440 $search-notice-bg = #c97a7e41

42 ////////////////////43 // TEXT COLORS44 ////////////////////45

46 // main content text color47 $main-text = #4c555a48 $nav-text = #4c555a49 $nav-active-text = #2d92c850 $nav-hover-text = #2F343751

52 // color of unselected language tab text53 $lang-select-text = #d0d4d754

55 // color of selected language tab text56 $lang-select-active-text = #fff57

58 // color of language tab text when mouse is pressed59 $lang-select-pressed-text = #fff60

61 ////////////////////62 // SIZES63 ////////////////////64

65 // width of the navbar66 $nav-width = 220px67

68 // portion of the screen taken up by code examples69 $examples-width = 45%70

71 // margin between nav items and logo, ignored if search isactive

72 $logo-margin = 100px73

71

74 // padding to left and right of content & examples75 $main-padding = 34px76

77 // padding to left and right of navbar78 $nav-padding = 20px79

80 // padding used vertically around search boxes and results81 $nav-v-padding = 8px82

83 // extra padding for ToC subitems84 $nav-indent = 10px85

86 // padding inside code annotations87 $code-annotation-padding = $main-padding88

89 // padding under the largest header tags90 $h1-margin-bottom = 21px91

92 // min width before reverting to tablet size93 $tablet-width = 930px94

95 // min width before reverting to mobile size96 $phone-width = $tablet-width - $nav-width97

98 ////////////////////99 // FONTS

100 ////////////////////101

102 $default-font103 font-family: "Lato", "Helvetica Neue", Helvetica, Arial,

sans-serif104 font-size: 16px105

106 $header-font107 @extend $default-font108 font-weight: bold109

110 $code-font111 font-family: Monaco, Consolas, Menlo, Monaco, "Lucida

Console", "Liberation Mono", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Courier New", monospace,serif

112 font-size: 13px113 line-height: 1.5em

72

114

115 $font-icon = FontAwesome116 $font-icon-path = "fonts/fontawesome-webfont"117 $font-icon-version = "4.0.3"118

119 ////////////////////120 // OTHER121 ////////////////////122

123 $nav-active-shadow = transparent124 $nav-footer-border-color = #666125 $nav-embossed-border-top = #000126 $nav-embossed-border-bottom = #939393127 $main-embossed-text-shadow = 0px 1px 0px #fff128 $search-box-border-color = #666129

130 ///////////////////////////////////////////////////////////////////////

131 // INTERNAL132 ///////////////////////////////////////////////////////////////////////

133 // These settings are probably best left alone.134

135 $break-words136 -ms-word-break: break-all137 word-break: break-all138

139 /* Non standard for webkit */140 word-break: break-word141

142 -webkit-hyphens: auto143 -moz-hyphens: auto144 hyphens: auto145

146

147 ///////////////////////////////////////////////////////////////////////

148 // Coowry Specific149

150 $aside-warning-bg = #ffc510151

152 .tocify-wrapper > img153 max-width: 65%154 margin: 20px auto;

73

155

156 header157 padding: 0 34px158 margin-right: 45%159 margin-top: 2.5em;160 margin-bottom: 0.8em;161

162 section163 padding-left: 505 px164

165 pre code166 white-space: pre-wrap167

168 // Do not use standard HTML link style169 @css {170 a {171 text-decoration: none;172 }173 a:link, a:visited {174 color: #2d92c8;175

176 }177 a:active {178 color: #ffc510179 }180 }

B.3. Código Nunjucks a PDF (Md)B.3.1. Index

1

2 {# Macro needed to change responses keys 460 and so on to400 and 470 and so on to 412 #}

3 {% macro changeK(controlKey) %}{%if ((controlKey<470) and (controlKey>459))%}400{%elif controlKey>469 %}412{% else%}{{controlKey}}{% endif %}{% endmacro %}

4

5 {% set controlKey=400 %}6

7 {% set comma = joiner() %}8

9 # Introduction10

74

11 {% if description %}12 {{description}}13 {% endif %}14

15 #### Endpoint16

17 {% if version %}- **version** {{ version }}{% endif %}18 {% if baseUri %}- **baseUri** {{ baseUri }}{% endif %}19 {% if protocols %}- **protocols**20 {% for protocol in protocols -%}21 {{ comma() }} {{protocol}}22 {%- endfor %}23 {% endif -%}24 {% if mediaType %}- **mediaType** {{ mediaType }}{% endif

%}25 {% for indice in securedBy.length | dump %}26 {% if securedBy %}- **securedBy** {{ securitySchemes[

securedBy[indice-1].schemeName].type }}{% endif %}27 {% endfor %}28

29 {% for item in documentation %}30 # {{ item.title }}31

32 {{ item.content }}33

34 {% endfor %}35

36 # Resources37

38 The following chapters contains resource descriptions.39

40

41 | Resource | Description |42 | --- | --- |{% for resource in resources %}43 |{% if resource.displayName %}**{{ resource.displayName

}}**: {% endif %}‘{{ resource.parentUrl }}{{ resource.relativeUri}}‘ | *{{resource.description}}*

44 |{% for resource in resource.resources %}45 |{% if resource.displayName %}**{{ resource.displayName

}}**: {% endif %}‘{{ resource.parentUrl }}{{ resource.relativeUri}}‘ | *{{resource.description}}*

46 |{% for resource in resource.resources %}47 |{% if resource.displayName %}**{{ resource.displayName

}}**: {% endif %}‘{{ resource.parentUrl }}{{ resource.

75

relativeUri}}‘ | *{{resource.description}}*48 |{% endfor %}{% endfor %}{% endfor %}49

50

51 {% for resource in resources %}52

53 {% include "./resource.nunjucks" %}54

55 {% endfor %}

B.3.2. Resource

1 # {% if resource.displayName %}{{ resource.displayName }}:{% endif %}‘{{ resource.relativeUri}}‘

2

3 {{ resource.description }}4

5 {% if resource.allUriParameters.length > 0 %}6 | **URI Parameter** | **Description** |7 |--- |--- |{% for param in resource.allUriParameters %}8 | **{{ param.displayName }}** | {{ param.description }} |{%

endfor %}9 {% endif %}

10

11 {% for method in resource.methods %}12 ## {{method.method | upper}}13

14 {{ method.description }}15

16 {% if method.queryParameters %}17 ### Query Parameters18

19 | Parameter | Type | Required | Description |20 |--- |--- |--- |--- |{% for param in method.

queryParameters %}21 | **{{ param.displayName }}** | *{{param.type}}* | {% if

param.required == true %}Yes{% else %}No{% endif %} | {{param.description }} |{% endfor %}

22 {% endif %}23

24 {% if method.body.length > 0 %}25 {% set body=method.body[0] %}26 ### Request27

76

28 {% if body.properties.length > 0 %}29 | Parameter | Type | Required | Description |30 |--- |--- |--- |--- |{% for param in body.properties %}31 | **{{ param.displayName }}** | *{{param.type}}* | {% if

param.required == true %}Yes{% else %}No{% endif %} | {{param.description }} |

32 | | | | |{% endfor %}33 {% endif %}34

35 {% for example in body.examples %}36 {% if example.value and example.value != "{}" %}37 #### Sample Request with ‘cURL‘38

39 ‘‘‘bash40 $ curl -u $PUBLICKEY:$PRIVATEKEY -X {{ method.method |

upper}} \41 -H "Content-Type: application/json" -d ’42 ‘‘‘43 ‘‘‘json44 {{ example.value }}45 ‘‘‘46 ‘‘‘bash47 ’ {{baseUri}}{{ resource.parentUrl }}{{ resource.

relativeUri }}48 ‘‘‘49 {% endif %}50 {% endfor %}51

52 {% endif %}53

54 {% for response in method.responses %}55

56 {# Here we save the real key of the response (460.. -> 400& 470.. -> 412) #}

57 {%set controlKey = response.key%}58

59 {% set body=response.body[0] %}60 ### Response {{changeK(controlKey)}} {% if response.key !=

204 %} {{body.displayName}} {% else %} no_content{%endif %}

61

62 | Code | Type | Description |63 |--- |--- |--- |

77

64 | **{{changeK(controlKey)}}** | *{{response.body[0].displayName}}* | {{response.body[0].description}} |

65

66 {% for example in body.examples %}67 #### Sample Response68

69 ‘‘‘70 {{ example.value }}71 ‘‘‘72 {% endfor %}73 {% endfor %}74

75 {% endfor %}76

77 {% for resource in resource.resources %}78 {% include "./resource.nunjucks" %}79 {% endfor %}

78

Este documento esta firmado porFirmante CN=tfgm.fi.upm.es, OU=CCFI, O=Facultad de Informatica - UPM,

C=ES

Fecha/Hora Wed Jun 06 23:10:25 CEST 2018

Emisor delCertificado

[email protected], CN=CA Facultad deInformatica, O=Facultad de Informatica - UPM, C=ES

Numero de Serie 630

Metodo urn:adobe.com:Adobe.PPKLite:adbe.pkcs7.sha1 (AdobeSignature)

trabajo fin de grado documentación y ajustes de un api...

Documents