What is the canonical location of the RAML file for an API?


#1

Where should the RAML file be served from for an API?


#2

i, too, would like to know


#3

What about the base of your API? Eg. /api/{name}.raml


#4

What would {name} stand for in this case?


#5

I think we want something more conventional, something where you can always now how to get to API spec without having to know a name or other details that may be in the spec itself.

WSDL has {baseUri}?wsdl and it’s really well-known, so we could have {baseUri}?raml but it’s not a very attractive (IMHO) resource and it also looks like a query parameter without a value. I’m hoping we can do something better.

Another idea is {baseUri}/api.raml which looks like a reasonably descriptive resource. I’m not crazy about having the media type be indicated by the extension in the URL, I prefer to get it in the Accept header, which would indicate {baseUri}/api with a Accept: application/raml+yaml.

What do others think?


Generate RAML for existing API
#6

I would highly prefer that the file be retrievable through a GET with no header needed so that one can obtain it through a browser command.


#7

I tend to agree with @rezaloo. Maybe a GET on {baseUri}/raml or {baseUri}/specs/raml, which would return the canonical raml spec for the API?


#8

I personally would prefer the (albeit not super elegant but industry-accepted) {baseUri}?raml to {baseUri}/raml because I don’t think the API spec needs to be a resource on itself but can instead be a particular representation of the API root.


#9

First of all, I do not think this is something that the RAML specification should concern itself about.

Having said that, my two cents:

I do not like the Accept header approach, as it would be impossible to give someone a link and have them check the API out in the browser easily.

My objection to use {baseUri}?raml is that in this way, the root resource cannot be used cleanly in you REST API, which may or may not be a pattern that RAML discourages.

I feel that @comptly’s suggestion, adding a new resource where the spec is the target is more semantically clean that the others.


#10

Personally I would be inclined to just stick it at the root of the API.

I think there’s another way to look at it, too. Imagine referring to your API by saying “The API is located http://example.com/path/to/my.raml in the RAML format”. The RAML file knows the baseUri of the service, so why say anything else? In other words, you don’t need to get to the RAML file from the API, you only need to get to the API from the RAML file.

Another point to inform the discussion would be the proposal for “Home Documents”, at http://tools.ietf.org/html/draft-nottingham-json-home-02. However this takes a “follow-your-nose” approach to APIs, which is somewhat at odds with RAML.


#11

Let´s exploit a convention in the soap world. Just as one can query for a wsdl with endpoint?wsdl let´s do the same with endpoint?raml


#12

A single location isn’t a great idea in my mind as I believe you should be able to retrieve the descriptions of a single resource, or a sub-set of an API but not the whole thing.

Two options in my mind:

  1. GET request on /api/ or /api/resource/ with Accept: application/raml (or whatever the correct mediaType is)
  2. OPTIONS request on /api/ or /api/resource/

#13

Dan, see above in this thread for the drawbacks of this approach when using a browser.

Agreed that it would be nice for whatever proposal wins out to account for fetching pieces of the spec, but how would that work given resource types, traits, etc?


#14

In my mind this is not a purely technical discussion/decision it comes down what you consider this .raml file to be:

  • A resource in itself -> then define/use a canonical location (this needs to be reserved though)
  • A resource meta-representation -> then use same resource uri, and expose meta-representation via use of mediaType
  • Information about how to interact with a resource -> then use OPTIONS on resource uri, thats what it’s for.

Agree that all but the first are not ideal in browser, but thats simply because a browser is built to retrieve and display html representations of resource only. A simple browser plugin could augment this functionality to allow a user to obtain the api specification.

I don’t see much of an issue with splitting the raml file based on resource, types/traits would be defined in parent raml file and child specs would implicitly import the parent raml file I guess.