Define tu API en RAML

APIs API Definición de APIs RAML

5874 vistas

RAML es uno de los lenguajes de definición de Apis más importantes del momento. Se revisará qué particularidades tiene y cómo se define:

- Seguridad

- Servicios

- Parámetros generales

- Recursos

- Tipos de respuesta

- Proyectos open source alrededor del RAML

Publicar comentario con dirección de correo electrónico (se requiere confirmación de correo electrónico para publicar comentarios en el sitio web) o por favor iniciar sesión publicar comentario

40. Síguenos en @apiaddicts

39. Síguenos en @apiaddicts Ruegos y preguntas

5. Síguenos en @apiaddicts Documentación funcional Descripción a alto nivel de la APi

32. Síguenos en @apiaddicts RAML 1.0 RAML

33. Síguenos en @apiaddicts RAML 1.0 RAML

35. Síguenos en @apiaddicts RAML 1.0 RAML

36. Síguenos en @apiaddicts RAML 1.0 RAML

37. Síguenos en @apiaddicts Api Designer MADA

6. Síguenos en @apiaddicts Documentación Descripción técnica de la API

8. Síguenos en @apiaddicts Documentación - fakes Implementando un fake con las interfaces de entrada y salida

13. Síguenos en @apiaddicts SDKs Facilitan la integración con las Apis

34. Síguenos en @apiaddicts RAML 1.0 RAML

30. Síguenos en @apiaddicts Generando la documentación con RAML Documentación RAML

31. Síguenos en @apiaddicts Desde la consola podemos generar los casos de prueba a partir del RAML Casos de prueba MADA

11. Síguenos en @apiaddicts Se debe generar documentación clara y comprensible para los developers. Documentación Generar la documentación para el developer

12. Síguenos en @apiaddicts 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

24. Síguenos en @apiaddicts Desarrollo de una implementación con las interfaces de entrada y salida. Implementando el servicio fake RAML

25. Síguenos en @apiaddicts Api Designer posee una consola de pruebas Testeando la API RAML

27. Síguenos en @apiaddicts Proyectos Open Source RAML

28. Síguenos en @apiaddicts Proyectos Open Source RAML

26. Síguenos en @apiaddicts Proyectos Open Source RAML http://raml.org/projects

10. Síguenos en @apiaddicts 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

15. Síguenos en @apiaddicts 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

14. Síguenos en @apiaddicts 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?

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

9. Síguenos en @apiaddicts - 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:

7. Síguenos en @apiaddicts - 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

38. Síguenos en @apiaddicts 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

4. Síguenos en @apiaddicts 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:

3. Síguenos en @apiaddicts APIs más populares Google Maps Twitter YouTube Flickr Amazon Product Advertising Facebook Conociendo las Apis Crecimiento de las Apis

29. Síguenos en @apiaddicts Permite: ➢ Generar casos de prueba ➢ Validar los parámetros de entrada como de salida Importando un raml desde SoapUI Validando la API RAML

23. Síguenos en @apiaddicts 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

41. Síguenos en @apiaddicts Contacta en: Email: [email protected] Web: www.apiaddicts.org Siguenos en: ➢ Linkedin: ApiAddicts ➢ Twitter: @apiaddicts ➢ Facebook: APIAddicts ➢ Meetup: APIAddicts ➢ Meetup: APIAddictsBCN Contacta

18. Síguenos en @apiaddicts 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

17. Síguenos en @apiaddicts 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

2. Síguenos en @apiaddicts Patrocinadores ¿ Qué nos ofrece? Calle Velasco 13 Tlf: 658 89 75 75 [email protected] 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..

19. Síguenos en @apiaddicts 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

22. Síguenos en @apiaddicts 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" ] }

16. Síguenos en @apiaddicts 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

21. Síguenos en @apiaddicts 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

20. Síguenos en @apiaddicts 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