Beginner to Raml


Hello I’m completely new to RAML/YAML. I was wondering if anyone here is able to help me set this RAML/YAML step by step. I am planning on using sublime for RAML. A working (full) example of a RAML file would be appreciated so I can play with how it works. The tutorial was not beneficial and the URL it provided is out of date.

I want to know how to run RAML off of sublime.
I want to know if it is possible to automate API test using RAML.



First, I think the current tutorial is beneficial enough to get anyone started with a decent understanding of RAML. That said, I am sure when the 1.0 spec is finalized, we’ll start to see a lot more documentation and tutorials around RAML, especially given the adoption of RAML.

There is a project in the Projects link to get you set up to use Sublime 3 with RAML syntax color highlighting, but unfortunately the only “ide” that offers some sort of code completion is the API Designer project. It’s not hard to set up if you follow that Github documentation, but it does limit you to using HTML 5 storage with no way to export the files short of copy/paste. It’s a shame they don’t add that feature to it. There is an alternative version of API Designer (forget the URL but it’s in a forum post somewhere around here) that a developer did to allow you to use Mongo DB and centralize the use of the API Designer project. I have that set up myself and it too leaves a lot to be desired, but does work by storing all the files in mongodb as well as provides info on how to set up a 2nd port to pull the files via GET calls to the urls. The primary issue with the API Designer is larger files cause it to get really sluggish, so if you can keep your RAML files small, you should be fine.

As for API test automation, yes it is definitely possible. The goal of RAML, in my opinion, besides making it easier to “sculpt” API endpoints and documentation, is to use it as a single source of truth document. If you look at the various projects here, you will find php, python, ruby, java, and more in terms of SDK and/or server side code generation. While most of them are not stable and have some issues, it’s possible to use RAML for all these purposes. There is the ABAO test project that will test your RAML doc against a deployed implementation of the API the RAML doc describes. If you couple that with the JAX-RS code generator, for example, you could generate stub server side code, WAR it up, deploy it and then run ABAO against that to test that your RAML doc is implemented correctly. You can also use the RAML to generate unit tests that you then run with each build iteration or any change commits to a RAML doc.

The bigger issue besides waiting on the 1.0 spec to be released (and then wait for all the projects to get updated to use the 1.0 spec) is that most of the projects seemed to have started but not had much work done lately… leaving us to wonder if they are dead projects or are they all just stalled waiting for the 1.0 spec to come out before they get completed.

In the mean time, myself, and a few others are now trying to get SDK generation in place. Mulesoft built a nodejs/npm based “sdk code generator” project that takes a RAML doc and generates a javascript SDK. I am working on adding a Java SDK generator, and possibly looking at seeing if the JAX-RS project (separate project) could be added as a “language” to this generator so that the single project could generate client side and server side code.

Please jump in and help us make RAML that much better. Adding a language adapter to spit out junit automation tests would be a great addition that would benefit everyone in the community.


@justjacksonn - I couldn’t say more about it - thanks :wink:

Just one comment on the dead projects topic - I can’t speak for everyone, since I don’t have control about them, but for some I can say that they’re in development where some of them wait for the 1.0 release as things will change with that release. One project which will be released soon is an updated console with new UI and functionality and there is more to come this year :wink:

As @justjacksonn already said - if you could help to make RAML that much better, it would be brilliant. Contribution by any means doesn’t necessarily means to code or create projects or something, but also constructive feedback, a list of nice to have features, where can we improve, etc.!

For example - what do you think is missing in the RAML tutorial to ramp up new people like you?


@christian_vogel console… does that mean the API Designer will see an update too to handle much larger files, faster scrolling/refresh, and more features like working from disk or DB locations?


No, I am talking about the API Console - not the designer.


Ok… do you know by chance if the RAML parsers will be ready to work for java (and javascript) for the 1.0 release? Or will it be some time after the release of the spec? I am hoping the parsers work pretty close to when the spec is released so any tools relying on them can get upgraded pretty quickly.


I don’t have an answer on this right now - but yes I hope that will be the case too :blush:


Ah, that is very helpful to know. So the past 20 hours I been playing around with an example in API designer and was able to create a fleshed out api, I think…hopefully. I’m looking into how to automate and test the endpoints to return, for example status code: 200. Any links to help me in the right direction to automate this would be helpful.

After my “project” is finished I would be able to post most of my work minus credentials to help the community.


Do you want to simple mock your endpoints returning examples or do you need advanced logic executed inside your mock, eg returning specific status codes, responses, etc.?

For testing I would suggest you to take a look at the following projects:

Let me know if you need more.


Alright I chose Abao. Hopefully it’s the right one to use. I want to test an api endpoint but to get to those end points I need to get past authetication. How am I able to suppose to code that? Do I put the credentials or the token into the header?

Here’s my current code.

#%RAML 0.8

title: Content API
version: v1
baseUri: # -what-url-do-put-here-


  • oauth_2_0:
    description: |
    OAuth2 is a protocol that lets external apps request authorization to private
    details in a user’s GitHub account without getting their password. This is
    preferred over Basic Authentication because tokens can be limited to specific
    types of data, and can be revoked by users at any time.
    type: OAuth 2.0
    description: |
    Used to send a valid OAuth 2 access token. Do not use together with
    the “access_token” query string parameter.
    type: string
    description: |
    Used to send a valid OAuth 2 access token. Do not use together with
    the “Authorization” header
    type: string
    description: Unauthorized
    authorizationUri: #what-url-should-i-put-here
    accessTokenUri: #what-url-should-i-put-here
    authorizationGrants: [ credentials, code, token ]

securedBy: [ oauth_2_0 ]
mediaType: application/json



Thanks for the input.

I am using the mockup service of mulesoft

What if I want advanced logic inside my mock, for ex:
If I sent parameter password=“123” it should return "password too short"
If I sent parameter password=“123456” it should return “login successful”

Also I want a way to actually return and test 401 and 500 error codes, currently mock service always returns 200

Do you know a way to do that?



the existing documentation does explain RAML and its features quite well. What is missing is the setup and workflow to put the teaching into practice. For example: “How to use the API designer and build your JAXRS server and client code”, answering questions of

  • “Where are the raml files I design in the API designer persisted?”
  • “How do I get them into Java code?” or any other target language
  • “How do I do versions of the definition/generated code with git or any other SCM?”
  • "How to do releases?
  • “How to automate all this with maven/gradle and test automation/validation in a CI system?”
  • “How to collaborate on such things in a team?”
  • “Other best practices?”

Right now I see a lot of tools that look promising, and a bunch of variants like RAML Store with API designer, but there is little glue documentation that seems to work. All I can find are cryptic descriptions, that expect a familiarity with their build tools, such as node JS, NPM, Grunt, etc. . This limits the audience to a large degree.

– kaj


thanks kaj - definitely take that away. do you think it makes sense to have kind of documentation around this or more like an FAQ?


If it helps, thanks to Blake and Christian’s help, I was hoping to try my hand at a blog entry around using the RAML-GENERATOR project (which is essentially the RAML-CLIENT-GENERATOR project but slightly improved to allow separate projects to “require” raml-generator rather than git clone the raml-client-generator and add your additions to the languages/ folder.

I am still learning myself, so I will probably ask Blake/Christian to proof my blog before I publish it. Essentially what I would like to shoe is my “rudimentary” process for a java SDK generator. I think the individual project does an alright job getting you set up, but after that you’re left on your own to learn things, such as understanding how the nodejs “build” process with raml-generator works, how to customize it for specific purposes, such as creating individual .java source files for each resource in a RAML file, how to handle JSON Schema defined in a RAML converted to Java POJO classes, and more. I suspect this will take me a while to put together though, so don’t hold your breath that it will be ready tomorrow. :smiley:


Happy to review that @justjacksonn. Let me know