RAML User Story: Patrick Schiess

Jonathan Stoikovitch
RAML by Example
Published in
3 min readMar 19, 2018


Patrick is a graduate of Purdue University. He has been writing code since he was 11 years old and identifies as a full stack developer. In his spare time, he enjoys ballroom dancing with his wife, playing Overwatch, and solving technology problems with code.

Q: what is the problem you were trying to solve (with RAML)? Please describe the problem and give an example.

A: Originally I thought I wanted to use RAML for API documentation. I had prior experience with Swagger, but I wanted to give RAML a fair chance. I started reading and learning about RAML and quickly discovered that RAML is much more than an API documentation tool. The approach of using RAML to facilitate building APIs ‘design-first’ is incredible. Creating an API design and using a mocking service to get immediate feedback from my API consumers greatly reduces the amount of rework required during implementation. In my previous experiences, I would generate API documentation around my already-implemented code… so this was a major mindset shift.

Q: How did RAML help you solve that problem?

A: The community has done an incredible job building out tools that enhance the RAML experience. I really enjoy having interactive and consistent API documentation, so from that perspective RAML helps bring order to the anarchy. From a practice standpoint, RAML has offered a new way to solve a problem that we didn’t know we had: designing an API before implementing it. It’s easy to look back on previous projects and see where a design-first approach would have reduced the time to delivery. Looking forward, recent additions to RAML (such as fragments) will help us create a library of reusable business objects and representations- marginalizing our delivery time even further.

Q: What are the benefits you’ve gained as a result? You can either describe or quantify numerically.

A: In general, it can be hard to describe things. In the case of APIs, describing an API contract or an interaction pattern in a way that is meaningful to consumers can be even trickier. I’d say at this point in my RAML journey, I’ve probably spent ‘tens’ fewer hours describing how my APIs work. That doesn’t sound like much, but if we layer on a couple more years worth of API development projects- that number easily edges into the ‘hundreds’. In larger development organizations, one could argue that RAML could save ‘thousands’ of hours by facilitating API description and interaction.

Q: What feature(s) would you like to be added to RAML?

A: I think it would be great to have a way to describe GraphQL APIs or even full GraphQL support in RAML.

Q: Which tools would you like to see support for RAML?

A: I’d definitely love to see a visual editor for RAML. Perhaps something that takes people away from the actual YAML and puts them in a GUI? As I evangelize the importance of good API design and using a RAML/Design-first approach, I’ve noticed that some folks have difficulty dealing with the strictness of RAML/YAML. Having a solid investment in tools that facilitate the construction of RAML in a way that relates to the visually-inclined would be great!