Best way to refactor reused query parameters


#1

I am working on describing a large API with RAML, and it happens that almost all of the calls in this API share two query parameters: an “authorization” parameter that needs an access token, and an “accept” parameter to specify whether XML or JSON is returned in the response.

What would be the best way (if any) to avoid having to type those two out for all of the methods in the spirit of RAML? I’ve been mulling on the idea of an !include or maybe some kind of resourceType that I could apply to everything? Those seemed to fall through when I saw that an !include is treated as a string, and that apparently I can’t assign query parameters to a resource, only its methods.
Thoughts about how to approach this sort of thing?

A confused but intrigued developer,
-Ryan


#2

Hi Ryan,

In this case I would recommend using traits as following:

traits: 
  - pageable:
      queryParameters:
        offset:
          description: Skip over a number of elements by specifying an offset value for the query
          type: integer
          example: 20
          default: 0
        limit:
          description: Limit the number of elements on the response
          type: integer
          example: 80
          default: 10

/sessions:
  is: [ pageable ]
  get:
  post:

In the above example you define a pageable trait which defines two query parameter which you can use inside resources or operation, and it will automatically add the two parameter to the resource specification. If you define it on the resource level - it will be added to each defined operation.

Does this help?

Cheers,
Christian


#3

@christian_vogel

I’m looking for something like this. However I would like to have additional Query parameters for my resource along with the one’s defined in the trait.
Is this achievable?

Basically have both Queryparameter and Trait with in a resource.

traits: 
  - pageable:
      queryParameters:
        offset:
          description: Skip over a number of elements by specifying an offset value for the query
          type: integer
          example: 20
          default: 0
        limit:
          description: Limit the number of elements on the response
          type: integer
          example: 80
          default: 10

/sessions:
  get:
    is: [ pageable ]
    queryParameters:
      employeeId:
        description: Employee Id for which Employee data is needed
        type: string
        pattern: "[a-zA-Z0-9]+{1}"
        required: true
        example: "004fb925cb9d44b6b2fcbd605769e513"

Is this valid?


#4

Yes that is valid. See the API Console output:


#5

Hello Christian,
this seems not to work in Raml 1.0: I get an error “Traits should be a map in Raml 1.0” when using the Api Designer from Mulesoft.


#6

Hi @raml_man,

my post is quite old and the syntax is still based on the first release candidate of RAML 1.0. Just change - pageable to pageable.


#7

Hi Christian,

I just found this out. Thanks for replying anyway!