Back to Blog Archive

Leveraging inheritance in RAML

Posted on: March 2, 2020
Author:
Joseph Masini

Clean and concise code is a key in software development, with one of the biggest caveats being the reduction (but not elimination) of code documentation. Pairing the latter with modularity gives us an edge in reducing future development effort and keeping technical debt at bay.

In this blog post, we explore RAML, specifically its type-definition and inheritance mechanisms which enable type-reuse. We showcase the latter mechanisms and benefits by highlighting them using a case study.

Case Study

The ACME Vehicle Fleet Inc. company specialises in leasing land vehicles, including cars, trucks, and motorcycles. Recent success has prompted the company to expand its fleet and the creation of a system to track it. ACME are also looking to diversify their offerings with future introductions of other vehicles such as RVs, quad bikes and maritime-vehicles, but those details are not entirely clear at the time being.

Prompted with the possibility that this system may be accessed via several devices and interfaces to offer a complete experience, the development team decided to opt for a contract-driven solution (RAML) to develop an API that will serve as the interface for the functionality provided. The management would like to review a proof-of-concept (POC) before giving the final sign-off, including a showcase of the benefits and potential pitfalls.

From Requirements to Contract

The development team decided to focus on the vehicle registration process. The latter specifies that upon acquisition, the vehicle is issued a license plate, and the registration date and last recorded service date (if any) are noted.

Now, if we draft a quick RAML snippet of this functionality, we can come up with several types for the supported vehicles, and the operation to process the vehicle:

We can notice that some properties are shared, specifically Vin, Make, Model and Year. Since RAML supports inheritance, we can extract these to a generic type Vehicle. We then override the generic type of the concrete vehicles (which is by default type: object) to be of type: Vehicle.

The result is the following:

Inheritance has already given visible results, with a slightly smaller specification which is easier to reason about and maintain.

Now, after registration, the vehicle would be assigned an identification, registration date, license plate and the last service date (if any). Applying the concepts of inheritance further, we easily describe what a registered car would look like. Specifically, we abstract the notion of a RegisteredVehicle and apply multiple inheritances from the two types ([type1, type2]) together, to form the concrete registered vehicle:

With this POC in place, the development team goes to present this API snippet to the management. Some questions about the possibility of expansion to other vehicles might come up, including:

  • How much time would it take to add a new vehicle?
  • Would it break existing vehicle definitions?
  • Is the development of new endpoints necessary?

To showcase the simplicity of the update procedure, the development proposes to add an RV option. The latter has the same core properties as other vehicles but with the information about the RV. This includes the number of beds and what type of heating system it supports (if any).

The team also remarks that one possible optimisation is to group this behaviour under the notion of a ConcreteVehicle and RegisterdConcreteVehicle to further improve readability and maintainability.

Conclusion

Leveraging these techniques and patterns depends heavily on the design and requirements of the API. You will be hard-pressed, however, to find instances where this powerful facet of RAML reduces your efficacy in providing clean and maintainable code.


What do you think? Do you perceive this to be more readable and maintainable? Are there cases where such patterns can backfire? Let me know and we can discuss further!

Author:
Joseph Masini

2 Comments for “Leveraging inheritance in RAML”

  1. Ravish Jha says:

    Hi Joseph – Indeed. It will definitely make code more readable. But more importantly reusable. And as per me that’s the way to do it. Again it depends upon the imagination of developer / technical teams to define universal types much before they are opportunity to reuse.

    • Joseph Masini says:

      Hi Ravish, wholly agree with you. You need a fine balance for any technique to work effectively, and as you’ve mentioned, it’s up to the developer / technical teams to find this balance, via explicit design and intuition gained through experience(s).

Comments

Contact Us

Ricston Ltd.
Triq G.F. Agius De Soldanis,
Birkirkara, BKR 4850,
Malta
MT: +356 2133 4457
UK: +44 (0)2071935107

Send our experts a message

Need Help?
Ask our Experts!