RAML

Síguenos en @apiaddicts
28
meetups
1.100
API Addicts
18.000
visualizations
10K
4K 4K

Patrocinadores
¿Qué nos ofrece?
Calle Velasco 13
Tlf: 658 89 75 75
contacta@cloudappi.net
www.cloudappi.net
Gobierno de Apis
➢ Definición de recursos
➢ Política de versionado
➢ Políticas de seguridad
➢ Estándar de definición
➢ Estándares de desarrollo
➢ Documentación
➢ Monitorización
➢ Testing
➢ Billing
➢ Gestión de entornos
Desarrollo de Apis
Desarrollamos Apis en diferentes
tecnologías, como en Java (Spring),
PHP (Zend) o node.js (express).
Integración con terceros
Consumimos apis de terceros,
como las de facebook, twitter,
gmail o de otros tipos de productos,
como el CRM de Zoho, Odoo..

APIs más populares
Google Maps
Twitter
YouTube
Flickr
Amazon Product
Advertising
Facebook
Datos recogidos de programmable web
Conociendo las Apis
Crecimiento de las Apis

1) Realizar un documento funcional
2) Realizar el diseño de la API
3) Realizar una implementación fake
4) Implementar la API
5) Validar la API
6) Generar documentación para developers
7) Generar casos de prueba (códigos de ejemplo)
8) Generar los SDks
Desarrollo de Apis
Pasos:

Documentación funcional
Descripción a alto nivel de la APi

Documentación
Descripción técnica de la API

- Formato de la API (SOAP vs REST)
- Seguridad de la API,métodos de autenticación y autorización. Pj:
Basic, oauth1, aouth2…
- API Manager (wso2, apigee, genoa) vs ESB (Oracle Service Bus..)
Documentación
Consideraciones generales

Documentación - fakes
Implementando un fake con las interfaces de entrada y salida

- Lenguaje de programación y frameworks a utilizar
(java/springmvc, php/zend framework, node/express,.net/.net asp
Web API)
- Base de datos SQL vs noSQL
- Instalación en Cloud vs in-house
- Utilización de PaaS, IaaS. ¿Se deben utilizar servicios propios de
los Clouds?
- Pruebas de estrés, carga, rendimiento y volumen
Implementación
Consideraciones generales:

Una vez implementada la API, hay que
validar que la implementación cumple
con las especificaciones.
- Validación manual: Postman
- Validación automática (SOAPUI,
jMETER)
Testing
Validación de la API

Se debe generar documentación clara y comprensible para los
developers.
Documentación
Generar la documentación para el developer

Una de las cosas más importantes es generar casos de prueba
para que los developers puedan guiarse en la implementación.
Documentación
Casos de prueba

SDKs
Facilitan la integración con las Apis

1) Realizar un documento funcional SI
2) Realizar el diseño de la API SI
3) Realizar una implementación fake SI
4) Implementar la API SI
5) Validar la API SI
6) Generar documentación SI
7) Generar SDKS SI (por el momento)
RAML
¿Donde aporta Valor?

Todo los pasos en el desarrollo de una API deben partir de un único
documento, el de definición de la API.
Existen varios lenguaje de definición de APIs que permiten obtener
nuestra meta, de los cuales los tres más importantes son
RAML, SWAGGER y BLUEPRINT
MADA
Objetivo

La API se define en RAML, un lenguaje de definición de APIs.
#%RAML 0.8
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
- paged:
queryParameters:
pages:
description: The number of pages to return
type: number
- secured: !include http://raml-example.com/secured.yml
song**
Parámetros generales de la API Permite:
➢ Describir la API
➢ Incluir ficheros externos
➢ Utilizar propiedades
➢ Incluir schemas
➢ Definir la versión
➢ Definir el tipo de mediaAType
(pj:application/json)
➢ Protocolos (HTTP,HTTPS)
➢ Definir la URL base (URL en la que estará
desplegada)
➢ Definir documentación en formato Markdown
[MARKDOWN].
Documento de la API
MADA

Permite:
➢ Describir los parámetros de entrada, tanto query
parameters como uriParameters, indicando tipo,
descripción, valores por defecto, ejemplos de
valores...
➢ Definir los parámetros de salida (definirlo tanto
como json schema como por xml). Por ejemplo:
/songs:
is: [ paged, secured ]
get:
queryParameters:
genre:
description: filter the songs by genre
delete:
description: |
This method will *delete* an **individual
responses:
200:
body:
application/json:
example: !include examples/instagram-v1-media-popular-
example.json
Definiendo métodos GET y DELETE
Documento de la API
MADA

Permite:
➢ Describir los valores de entrada mediante
schemas (ya sean json o xsd)
post:
/{songId}:
post:
responses:
200:
body:
application/json:
schema: |
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "A canonical song",
"properties": {
"title": { "type": "string" },
"artist": { "type": "string" }
},
"required": [ "title", "artist" ]
}
application/xml:
Definiendo métodos POST
Documento de la API
MADA

Los traits permiten definir partes comunes de los recursos
traits:
- paged:
queryParameters:
pages:
description: number of pages
type: number
example: 8
song**
Definición
Traits
RAML
get:
description: obtiene los datos de un usuario
is: [paged]
responses:
200:
body:
application/json:
example: !include samples/users_get_id_200.json

Permite definir diferentes esquemas de seguridad
securitySchemes:
- oauth_2_0:
type: OAuth 2.0
describedBy:
headers:
Authorization:
type: string
queryParameters:
access_token:
type: string
responses:
401:
403:
settings:
authorizationUri: https://www.dropbox.com/1/oauth2/authorize
accessTokenUri: https://api.dropbox.com/1/oauth2/token
authorizationGrants: [ code, token
Definición
Securización
RAML
get:
description: obtiene todos los usuarios
securedBy: [oauth_2_0]
queryParameters:
sexo:
description: sexo a filtrar. Puede ser H o M
responses:
200:
body:
application/json:
example: !include samples/users_get_200.json
schema: Users

Permite definir un recurso completo y que otros hereden
resourceTypes:
- base:
get:
responses:
500:
body:
example: !include samples/base_500.json
Definición
Recursos
RAML
/users:
type: base
get:
description: obtiene todos los usuarios
securedBy: [oauth_2_0]
queryParameters:
sexo:
responses:
200:
body:
application/json:
example: !include samples/users_get_200.json
schema: Users

Permite utilizar schemas para el contenido de las peticiones / respuestas
schemas:
- Users: !include schemas/users_get.json
Definición
Schemas
RAML
{
"$schema": "http://json-schema.org/draft-04/schema#",
"id": "http://jsonschema.net",
"type": "array",
"items": [
{
"id": "http://jsonschema.net/0",
"type": "object",
"properties": {
"name": {
"id": "http://jsonschema.net/0/name",
"type": "string"
} }
],
"required": [
"0",
"1"
]
}

Permite utilizar schemas para el contenido de las peticiones / respuestas
documentation:
- title: introducción
content: !include
documentation/introduction.md
Definición
Documentación
RAML
introduction.md
# Requisitos legales
# Soporte

Desarrollo de una implementación con las interfaces de entrada y salida.
Implementando el servicio fake
RAML

Api Designer posee una consola de pruebas
Testeando la API
RAML

Proyectos Open Source
RAML
http://raml.org/projects

Proyectos Open Source
RAML

Permite:
➢ Generar casos de
prueba
➢ Validar los parámetros
de entrada como de
salida
Importando un raml desde SoapUI
Validando la API
RAML

Generando la documentación con RAML
Documentación
RAML

Desde la consola podemos generar los casos de prueba a partir del RAML
Casos de prueba
MADA

RAML 1.0
RAML

Api Designer
MADA

Existen Herramientas para generación de parte del código automáticamente
Permite:
➢ Generar código en Java
o Node
➢ Coexistir
implementación fake
con
Implementación
MADA

Ruegos y preguntas

Contacta en:
Email:
contacta@apiaddicts.org
Web: www.apiaddicts.org
Siguenos en:
➢ Linkedin: ApiAddicts
➢ Twitter: @apiaddicts
➢ Facebook: APIAddicts
➢ Meetup: APIAddicts
➢ Meetup: APIAddictsBCN
Contacta

RAML

Más contenido relacionado

La actualidad más candente

Destacado

Similar a RAML

RAML

Notas del editor