Like many of you (I suspect) I used to document my ORDS REST services using MS Excel or MS Word. Whilst better than not documenting them at all, I figured there had to be a better way. I am here to tell you that there is a better way and that is to use REST specification standards such as RAML, Swagger or API Blueprint. The standard itself is one thing but it is the tools that are born from these standards that really make the difference for me.
Not only can we create very nice documentation using simple markup, but we can also share it with our consumers at design time. In some cases, we can even auto-generate mock end points from the markup without writing any code. These end points can be called by our customer's client applications during design. All of this facilitates Spec Driven Development, which is a game changer in the API design world. You can now collaborate fully with your consumers before a single line of code has been developed.
I am not going to try and make this post about how to learn and use RAML (many have gone there already). The goal here is to open the hearts and minds of the ORDS to community to using a standard like RAML for their next project.
There are several standards out there (aren't there always) with Swagger, RAML and API Blueprint being the among the most prominent. I performed a Quick Search on Google Trends and see that by that metric at least RAML is trending upward:
BTW, looking under the hood at https://apicatalog.oraclecloud.com, it would appear Oracle is using Swagger.
Spec Driven Development
With a Spec driven design approach we focus on iterating together until we get a solid specification. At this point, you may ask "how is that different?". The main difference is in the tools. With tools like Mulesoft's Anypoint Platform and RAML, we can:
- Document the service in RAML and have the tool automatically generate HTML based documentation.
- Provide a web based portal to your developer community or consumers so they can see the service evolve. When you change the RAML, they immediately see the documentation reflect this change.
- Finally, (and this is the big one for me), the tool can generate mock end points (based on your RAML specification) which our consumers can call. This is without having to write a line of code.
Both sides can now start development at maximum velocity with the confidence that they have a good understanding.
Check out Mike Stowe's Blog for properties and advantages of Spec Driven Development.
"RESTful API Modeling Language (RAML) makes it easy to manage the whole API lifecycle from design to sharing. It's concise - you only write what you need to define - and reusable. It is machine readable API design that is actually human friendly."
My favorite aspects of RAML are:
- Easy to understand markup
- Generates clean, easy to understand documentation
- Tools available to auto-generate mock end points
- Great re-usability with 'traits', 'libraries' and 'data types'. This means if you use a certain type of security across all your APIs, you can define it once and then just reference it in all your services. Similarly, if you have a standard definition for a sales order, you can define it in a data type and then include that data type in your other services
RAML and REST Resources
Mulesoft - Anypoint Platform (https://anypoint.mulesoft.com)
- Web based platform
- Design REST API's Using RAML
- Live generation of documentation (as you type)
- Developer Portal available to share APIs
- Auto generation of mock end points
Mulesoft - API Workbench (http://apiworkbench.com/)
- Atom Package
- Create RAML to design REST APIs off-line
- Other RAML Tools:
RAML 100 Tutorial (http://raml.org/developers/raml-100-tutorial)
- Learn the Basics
RAML 200 Tutorial (http://raml.org/developers/raml-200-tutorial)
- Design a sample service End to End using RAML
- Mulesoft - Undisturbed REST Workshop
- Real World RAML specifications Created by other companies (such as Instagram, Spotify, Google, Slack etc.)