RAML Specification
RAML 1.0 was released nearly 5 years ago, in May 2016. Over time, a number of typos, grammatical errors and inconsistencies have been spotted and reported by the RAML community. We finally got around to fix most if not all of those and are bundling a myriad of fixes in a single 1.0.1 patch release.
No, this 1.0.1 release is a patch which means that it does not affect the validity of existing RAML 1.0 API definitions. In other words, the #%RAML 1.0 header remains unchanged.
The v1.0.1 Milestone contains references to all the clarifications included in this release. Most small typos have been grouped together in a single PR. These clarifications have also been ported to the RAML TCK, our official test suite for RAML processors.
With close to 800 members, the official RAML community Slack "raml-api" workspace is a great place to discuss anything RAML-related. If you're not already member, you can join here.
To our lovely RAML Community,
The RAML Workgroup is happy to ship a set of patches to our specification today. We don't bump any major or minor version for that, so everything stays as it is. The current version still be RAML 1.0! This patch release contains the usual clarification, content, and other fixes that will improve the specification.
Most changes are around clarification such as the any type or what kind of other built-in types do we have. People felt that this was missing, and we listen to all of you! You will find two brand new section here (the "Any" type) and here (Built-in Types). Furthermore, we changed the null type to nil to align better with the YAML spec. This change might impact existing RAML documents, but we did not want to wait until a minor release. Therefore, we think the best time for this is as early as possible.
Every other change was more around content improvement or fixing issues on examples. You can view a full list of changes here.
There will be most likely. Patch releases help us to improve the overall quality of the specification. Although we will not do any significant changes that impact existing RAML 1.0 specification; that we save for any future versions (major or minor) of the RAML specification.
The current pipeline for the next patch release are: clarifications on the union type to clarify what type: union is, and an algorithm how to resolve traits and resource types parameter. The former not introducing any changes to the current way using type expressions. No worries :)
Please continue to raise issues, give us advises and feedback, so that we can continue to improve RAML together.
The RAML Workgroup
With this release, the RAML Workgroup has finalized RAML 1.0 and approves it for general availability (GA) status. Since the first release candidate went out last fall, a tremendous amount of feedback and subsequent work has been invested to reach this milestone. Now that it is stable, and with the release in parallel of reference parsers, we look forward to reaping its benefits across the API landscape.
With 1.0, RAML introduces multiple new concepts that not only increase its core strength around designing APIs using libraries, fragments, and overlays/extensions, but also for documenting APIs.
New Features
Besides new features, the main focus for RAML 1.0 was also to create a more consistent and expressive specification. For that, we made several smaller changes, and some with a much bigger impact regarding the compatibility with the previous version.
Did anything change between GA and the latest release candidate?
Yes, we had some feedback from the community that we found crucial to change before we felt comfortable to release 1.0. The changes includes:
Other than these three, we only improved content and added some more clarification.
Will that be the last change in 1.0
Obviously we will continue to improve content and add clarification where we see the need to. Although, new features and/or changes to existing will be added to the candidates for our next release.
Where can you go from here?
And if you have any other question, please send us an email to [email protected], post something to our forum, or use our Gitter chat.
All changes during each release candidate and GA can be viewed here.
People that carefully watch our specification repository might have already realised that we were able to close all issues and merge the RAML 1.0 RC2 branch into its predecessor. Therefore, we are very happy to finally announce the official release of our next release candidate RAML 1.0 RC2.
The tremendous amount of work that participants from the community and RAML Workgroup put into this milestone got the 1.0 specification to a point where we consider making the RC2 our final version regarding its feature set. That means we will not make any more changes regarding functionality to the specification this release. Hence, between finalizing the specification and closing RAML 1.0 for GA, we will only work on several content improvements such as wordsmithing, English, adding more clarity in wording and examples, etc. But to move towards finalizing RAML 1.0, we will not be adding any new feature requests to this release, but instead will reserve them for our roadmap post 1.0. We will work on the content changes for the next coming week before closing and officially release RAML 1.0.
For a full list of changes compared to its predecessor, please see our RC1 vs RC2 wiki page.
It's a big day for RAML. We're excited to announce the publication of the RAML 1.0 (RC) spec.
What's new with RAML 1.0?
RAML has always been about making it easy for developers to manage the whole API lifecycle from design to implementation to operation and sharing. It's a concise, intuitive language for specifying APIs that allows developers to only write what they need to define an API, drawing from and contributing to commonly-used patterns, such as the YAAS (SAP hybris) pattern library.
With RAML 1.0 (RC1), we've added a clean new data modeling language, enhanced support for examples, strongly-typed annotations that allow extending an API spec in a controlled manner, and overlays and extensions to further modularize the API and keep interface and implementation separate. In particular, annotations and overlays can make it a cinch for partners or third party collaborators to attach testing, monitoring, and client and server generation to APIs based on their RAML specifications.
We'll keep it in an RC (Release Candidate) state to collect feedback, to catch and clarify any gray areas and corner cases, and clean up some of the language, before declaring it final.
On behalf of the RAML Workgroup, I am excited to unveil the RESTful API Modeling Language today as an open spec. This project’s been under development for quite some time, while we’ve been battle testing it and utilizing it to improve our own internal APIs. As we began socializing the spec for feedback from several API experts, we were humbled to see mounting interest from folks who got deeply interested in collaborating on the direction of the spec. As a provider, an API is the capability you offer others (inside your company or outside) to derive your value, to add theirs, to create and realize opportunities. As a consumer, an API is what you build on to realize the provider's value or to generate even more value. So an API is a contract between provider and consumer, around an interface. Both the provider and the consumer have to build around a common definition for that API. The success of the API depends on how well this contract works, as well as how well it’s implemented on both sides. RAML is a language for expressing that interface, that contract, optimized for the users of the contract: the consumers and the providers. In defining RAML, we looked to address some of the practical and pervasive problems across nearly all APIs. It seeks to address the overarching concerns of any API strategy, in as lightweight a way as possible:
In an ideal world, you could design the API to fit these needs, nail down the design in a spec, then implement the spec. But you don't necessarily know your needs immediately: you have to iterate a bit, play with it, until you have it right. Same as when you develop a killer UI. So you need a design-first approach to your APIs, and you need it to be easy and agile… how do you do that? Say hello to RAML. RAML emerged to the world today. You can expect new projects and tools to be available very shortly to help further show the benefits of RAML, of a design-first approach, and of a consumer-oriented strategy. In the meantime, I encourage you to have a look at the RAML tutorials to see just how we’re approaching things.