RAML: variable endpoints in different clients on an SAAS platform


#1

I am looking for someone who has ideas on how to best manage varying endpoints for different clients in an SAAS.

For example, in a platform that does vehicle sales, imaging several clients that have endpoints for vehicles, grouped by type

/vehicles/cars
/vehicles/trucks
/vehicles/boats
/vehicles/airplanes

but some apps in the platform only have cars, or boats, not the other two, and some have /bicycles - it totally depends on what is setup in their database.

My api is setup by client - so it is really:

/joescars/vehicles/cars
/joescars/vehicles/trucks

/northsideauto/vehicles/cars
/northsideauto/vehicles/motorcycles

My specific question is - how can I use RAML to model the api for my system(s) - for the different clients? Is the only way to do it using auto-generated raml? Which means writing code to get RAML?

Building the variability in the api is relatively easy, for example in express, with parameters:

/:clientname/vehicles/:vehicletype

Are there similar approaches using RAML?

I’ll admin I’ve only read the 100 and 200 tutorials - but don’t want to become an expert before finding out I can’t do this.

I will also be asking a follow-up - what about variable fields, and creating example responses? For example, some dealerships might provide make, model, and color at the cars endpoint - another make, model, cost, and condition or something.

Anyone with experience in this area - looking forward and thanks in advance.


#2

Is the only way to do it using auto-generated raml?

I think you’ll find RAML even more useful the other way around. That is, modeling your API using RAML first, and then either generate your code based on or ensure you hand-written code complies with your RAML API specification.

RE: “parameters”, RAML provides a way to do exactly what you describe, in a similar fashion to what Express provides, here’s the link to the relevant section of the specs.

RE: “variable fields”, you’ll want to check-out the type system referred to as RAML data types introduced in RAML 1.0. It is a concise, powerful and reusable way to describe fields/properties/schemas that can be reused and extended throughout the different parts of your API definition such as headers, requests and responses.

RE: “example responses”, RAML encourages and facilitates the inclusion of examples in your API specification. In fact it provides a way to not only include one example but multiple examples that can be used in your responses. The relevant section in the RAML spec is here.

Hope that helps!


#3

I think you might be missing the point of the question here - and it is complicated so please hear me out. One client might have 2 vehicle endpoints, cars, boats - one 6 (trucks, vans, bicycles) - each of those will have very different underlying data, different fields in particular. There are 100, or 1000 clients, in a SAAS platform. How would it make sense to use RAML to model the API, that we use to deliver each individual API? The APIs share a codebase - but there is one API in a real sense for each client in the platform, at

mydomain.com/api/--clientName--

and each has commonalities, but many difference. It seems that much or must of the usefulness of writing RAML first is lost - have you worked with such a use-case before? (and if you haven’t but still believe you are right that is fine - I just wonder if you thought far enough through this example to see that the RAML would be much more general than what I’m seeing in typical examples out there as I learn about it - and I don’t know if its usefulness would be lost, and if there is any point to writing it)


#4

The main question here is how much can be reused across all your multi-tenant APIs? i.e. commonalities.

If the answer is “none”, then there is nothing to reuse. Therefor the reusability aspect of RAML - at least “at scale” - is lost and one would need to model these APIs individually. One could still reuse pieces within any of those individual APIs though so the reusability aspect is not totally lost.

If the answer is “a lot”, then RAML would be a great tool for modeling those APIs because it focuses on reusability and offers many features such as resourceTypes, traits, data types, librairies, overlays that allow for writing more with less. This means that you can reuse pieces but also inherit from those pieces in cases where the “differences” are simply additional layers.

My guess is that the reality of your SaaS platform is probably somewhere in between and that while pieces such as headers, requests and responses might be shareable across all your tenants, other pieces might not.

I have personally modeled APIs for a SaaS platform that had tenants in the thousands and this is exactly why we chose RAML back then. We built a “base” RAML and added overlays on top.


#5

Excellent - that answers it perfectly - I will start diving in and learning these aspects of RAML. Thanks much.


#6

Anytime. Feel free to join our Slack workspace [1] if ever you need “live” support :wink:

[1] https://join.slack.com/t/raml-api/shared_invite/enQtMjg2Mzc0MTc4NjI1LWE4MGEwZDg2ZWQyYzI5NWYzNTE0NTU3MTc1MGVjZDE3NGJjZmRmYzlkNGM1NmQ2MTgzMzM0MDEzM2VhNDNmMDE