Single or multiple api spec files


#1

Hi,

Is there a best practice on the number of roots to have in your overall spec?
Or another way of asking the same question. Should I have just one file with all the API specific spec?
I know I can put schemas, resourceTypes and traits in separate files.
I’m talking about uri mappings here. For example: (a very simple contrived example)
my API has 2 types of resources:
/users
/products

should I put these in one file or is it ok to have them in two separate raml files, each having a root?

Apologies, if this question has been asked and answered before. I searched but I couldn’t find it.

Thanks
Thomas


#2

There is no “right” way, it’s totally up to you. Although RAML does encourage breaking down API Spec documents into as many pieces as possible – the same way you would do with code – in order to keep things organized, clear and DRY/re-usable.

RAML has two major mechanisms for externalizing parts of your API Spec, namely RAML fragments and includes. The former requires to defines a series of documents under the root-level node “uses”. The latter is a little bit more flexible, in that it allows for inclusion – using the special tag !include – of external files regardless of whether they are RAML fragments or not. You can read more here.