Introduction
Most folks reading this know that Oracle REST Data Services (ORDS) is a great way to bring your aging Oracle Database systems into the world of REST services. ORDS provides a fully functional, robust and secure REST infrastructure that you can have up and running in hours. What may not be as obvious, is that because ORDS services are standard REST end points, we can utilize 'standard' tools for documenting them.
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.
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.
Which Standard?
|
|
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:
|
To be honest, I chose RAML based on reading the book Undisturbed REST by Michael Stowe. If you have not already read the book, then you should. The book offers a pragmatic look into REST concepts and design principals with some real world insights to boot.
BTW, looking under the hood at https://apicatalog.oraclecloud.com, it would appear Oracle is using Swagger.
BTW, looking under the hood at https://apicatalog.oraclecloud.com, it would appear Oracle is using Swagger.
Spec Driven Development
For business to business services; we have traditionally written a design document (in Word or Excel), reviewed it with our consumers and signed in blood that we will adhere to the 'contract' which the design represents. We then went our separate ways and built our service or client app. The problem arose when we met again after two weeks to do a real live test of the service. Only then did we realize how different our understanding of the design was and that we have a lot more work to do.
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:
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.
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.
RAML
What is RAML? From raml.org:
"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:
"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
Blogs & Books
Tools
Tutorials
Example Specifications
- Blog from Mike Stowe What is Spec Driven Development
- Blogs from RAML.ORG
- Undisturbed REST eBook
Tools
-
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:
Tutorials
-
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
Example Specifications
-
https://github.com/raml-apis
- Real World RAML specifications Created by other companies (such as Instagram, Spotify, Google, Slack etc.)
Conclusion
Oracle ORDS can host REST services just like any other tool such. Given that, we should be using industry standard tools to design our ORDS REST services. Hopefully you can see that using a standard like RAML is not just about using standards. It actually makes your life easier and more importantly it improves the life of the people who are going to consume your services. Using a combination of RAML, the associated tools and a Spec Driven Development approach with your next Oracle ORDS project will pay dividends.
RSS Feed