Comments/questions on RAML


#1

Hi All,

Just discovered RAML - very interesting!

A few initial comments:

(1) A lot of RESTful APIs use accept headers to express version instead of having it incorporated in the uri/path. I suggest this option be provided in the spec. See http://stackoverflow.com/questions/389169/best-practices-for-api-versioning

(2) Please consider using “Path Param” instead of uriParam, since it aligns better with JAX-RS.

(3) How can one extend the language to support other constructs, like RBAC security authorization statements? I think this is a must have to be able to provide extensions to the expressions, not just for security but for anything.

Thanks,
Jeff


#2

Hi @trentjeff - first of all thanks for your comments and great you discovered RAML :wink: Let me try to go through each of your points:

(1) The API version is an optional requirement. You can easily do that right now - even dedicated resource versioning is possible:

#%RAML 0.8
title: Use Case 3 API
baseUri: http://localhost:8081/api

traits:
  - versionable:
    headers:
      version:
        description: place the version of this resource
        example: v1.0
        default: latest
        required: true
        type: string

/d:
  is: [ versionable ]
  get:
    responses:
      200:
        body:
          application/json

(2) Indeed, ‘pathPram’ might sound more obvious. Let’s see what everyone else says.

(3) Extension will be introduce to RAML 1.0 with ‘x-’ types similar to what you can do inside Swagger. Not really sure if that is what you’re looking for.

Hope that helps you.


#3

As per the path param, I too, coming form JAX-RS thought uriParam didn’t fit as well. However, and I am a JAX-RS fan… I fear using path param for the sake of making sense of JAX-RS is limiting the spec. If Path param fits for every other (or most anyway) language syntax such that various libraries for different languages use the same term, I’d agree with it. Otherwise, I’d argue that URI param fits just as well since it is the URI where the parameter resides and it seems more generic which may work well across language implementations. Just my .02 on the matter, I am fine either way though.


#4

Thanks for all of your input. I’m especially looking forward to the extensions portion. When will an early access version of that be available? I could used this today :slight_smile: If the suggestion is to use Swagger, will there be a migration path to/from Swagger and RAML?


#5

Hi @trentjeff - you might want to have a look on https://github.com/mulesoft/swagger-to-raml-object


#7

Hi @christian_vogel, I did like you write but I get “each header must be a map”!

/locations:
      is: [ versionable ]
      get: 

And the declaration:

  - versionable:
      displayName: versionable
      headers:
        description: place the version of this resource
        example: v1.0
        default: latest
        required: true
        type: string

I’m using the apidesigner online.

Tks


#8

Hi @zendron, thanks. can you post your RAML - I might be able to help you :wink:


#9

Hello @christian_vogel, it was my error, I forgot the name of the header:

 - versionable:
      displayName: versionable
      headers:
        version:
          description: place the version of this resource
          example: v1.0
          default: latest
          required: true
          type: string 

Now my api has version!

Tks


#10

Cool - cheers @zendron