RESTfulA PIM odelingL...
Transcript of RESTfulA PIM odelingL...
![Page 1: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/1.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
RESTful API Modeling Language
How to design your API with RAML
Ola Deibitsch| [email protected]
1 1
![Page 2: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/2.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
Problem SOAP got WSDL, but how do we describe a REST API?
2
SOAP/WSDL Complex Constraints (XML 1.0 & UPA) Structured
REST/? Simple Lightweight Structured
![Page 3: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/3.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
How do Users build API:s Today? SOAP got WSDL, but how do we describe a REST API?
3
JAX-RS annotations*…
WADL…
Swagger… Apiary Blueprint…
Google Discovery Docs…
Mashery I/O Docs…
![Page 4: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/4.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
RAML RAML by the RAML Workgroup
4
"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.", www.raml.org
![Page 5: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/5.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
DEMO: Callista Care API Requirements Callista Care API:
• Resources: – /patients – /patients/{patientId} – /patients/{patientId}/notes – /patients/{patientId}/appointments – …
• Verb – Get/Post/Put/Delete…
• Metadata – Authorization Header – Filtering
• Representations: – JSON, XML, ?.
5
![Page 6: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/6.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
RAML Tooling RAML IntroducTon
• API Designer – RAML Editor – RAML Console
• API Notebook • APIkit • SoapUI RAML Plugin • JAX-‐RS Codegen • … See more at www.raml.org
6
![Page 7: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/7.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
DEMO: Callista Care API (cont.)
1. Design using the API Designer. 2. Implement using Mule Studio and APIkit plugin. 3. Test using APIkit’s embedded RAML Console or
directly in API Designer
7
![Page 8: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/8.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
RAML Tooling: RAML -‐> JAX-‐RS JAX-‐RS Codegen
8
![Page 9: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/9.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
Summary
ü ”Simple”, ”Succinct”, ”Reuse”, ”Pa2ern-‐Sharing”, ”Vendor-‐Neutral”…
ü Consump:on & Producer Friendly ü API Documenta:on
! TOO EASY NOT TO TRY!
9
![Page 10: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/10.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
REST Fundamentals
• Verbs: HTTP methods • Metadata: HTTP headers • Nouns: HTTP resources, desribed by URI paths. • Responses: HTTP status codes • RepresentaTons: media type in the body
10
![Page 11: RESTfulA PIM odelingL anguage0beta.callistaenterprise.se/assets/presentationer/cadec-2014-raml.pdf"RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful](https://reader034.fdocuments.us/reader034/viewer/2022051910/5fffb3d9584dc36f0c57cb5b/html5/thumbnails/11.jpg)
© 2014 Callista Enterprise | www.callistaenterprise.se RESTful API Modeling Language -‐ RAML
API Explosion?
11