Provide different examples based on input values

[jantoniucci]

Add support to specify different examples on resources based on input values: uri parameter, query parameters, headers, etc.

A naif proposal:

#%RAML 1.0
title: PoC on examples including inputs
version: v1
protocols: [ HTTPS ]
baseUri: /api/{version}
mediaType: application/json
/foos/{fooId}:
  uriParameters:
    fooId:
      type: integer
  get:
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              name: string
              age?: integer
            examples:
              foo1:
                description: when is called as /foos/1
                uriParameters:
                  fooId: 1
                content:
                  name: "foo1"
                  age: 1
              foo2:
                description: when is called as /foos/2
                uriParameters:
                  fooId: 2
                content:
                  name: "foo2"
                  age: 2

[usarid]

That's pretty cool! Let's not put it into 1.0 at this late stage, but rather pursue the idea through annotations and see if we can come to a relatively general solution to this long-standing and important need, then consider standardizing it in a future version of RAML.

[jantoniucci]

It's very usefull to feed a mock server with input driven examples, please vote it!

[usarid]

You can absolutely do that, just define annotation types that your mocking server will recognize.

[jantoniucci]

Oh, yes! This is the way I am taking (see next raml example) but I am looking for a standardized one.

#%RAML 1.0
title: PoC on examples including inputs
version: v1
protocols: [ HTTPS ]
baseUri: /api/{version}
mediaType: application/json
annotationTypes:
  exampleInput: !include annotations/example-input.raml
/foos/{fooId}:
  uriParameters:
    fooId:
      type: integer
  get:
    responses:
      200:
        body:
          application/json:
            type: object
            properties:
              name: string
              age?: integer
            examples:
              foo1:
                (exampleInput):
                  inputType: uriParam
                  inputName: fooId
                  inputValue: "1"
                description: foo1
                content:
                  name: "foo1"
                  age: 1
              foo2:
                (exampleInput):
                  inputType: uriParam
                  inputName: fooId
                  inputValue: "2"
                description: foo2
                content:
                  name: "foo2"
                  age: 2

[usarid]

Mainly because we need to draw the line somewhere to be able to say we have a complete list of features for RAML 1.0 and publish it (and its parsers) -- hard for anyone to build on a spec that evolves continuously.

[jantoniucci]

Absolutely! And all of you are doing an excellent work very appreciated by all of us. Thanks!

[usarid]

Thank you for the suggestion and the support!

[chrpinedo]

I would add to this suggestion to be able to provide not only different example but also different responses (200/400/.., schemas, ...) based on the input values (uri parameter, query parameters, headers, etc.).

[freddrake]

I think a specification that addresses this topic would be very welcome, and give API specifications and tool builders a common language. (A better situation that having several similar but not-quite-parallel specifications thrown together by tool developers.)

However, it can reasonably be implemented as an extension using annotations. While RAML 1.0 is fresh, that's only because it's already been through an evolutionary & consensus building process. The new set of capabilities you describe would just be starting. Being able to evolve in parallel seems valuable, at least until both are considered stable. And once you hit that point, you don't need to merge them.

[jantoniucci]

Yes, actually we are using the following annotation that is enough flexible to define uri, params, body and headers inputs.

Nevertheless, I prefer a standard solution from the RAML specification. This will add maturity and common language.

#%RAML 1.0 AnnotationTypeDeclaration
displayName: exampleInput
description: input values for an example
allowedTargets: NamedExample
usage: define inputs to activate an specific examples declaring param types, names and values
type: array
items:
  properties:
    inputType:
      description: defines the input type (uriParam, queryParam, header, body), fill the input type using as values uriParam, queryParam, header or body
      enum: [ uriParam, queryParam, header, body ]
      required: true
    inputName:
      type: string
      description: defines the input name, fill the input name using the uri param name, query param name, etc exactly as is defined in the resource
      required: true
    inputValue:
      type: string
      description: defines the input value, fill the input name using the value to be checked
      required: true

[usarid]

If you find this approach really working, and can publish it as a library and promote it so it gets popular and gets validated by a broad base of users, it'll make it easier to consider for standardization at some future point. Thanks!

[jantoniucci]

done! available at https://github.com/jantoniucci/raml-spec-exampleInput

This is a RAML spec proposal to optionally define the inputs that produces the example.

These inputs could be uriParam, queryParam, header, body.

The proposal is implemented and currently used as an annotation but should be considered to be included as an example's property.

Specifying the inputs for an example is specially usefull to show expected response but also to feed a mock server.

Please, star and feel free to contribute.

[sichvoge]

@jantoniucci i started a raml-annotations repository to collect common annotations out in the community. can you fork and create a PR to add your into the annotations folder? there is also an explanation on the contribution part and what you need to do.

let me know if you have any questions.

[Kanchan-Shagalolu]

Hi Team,

Any updates on the status of this to support this feature? We also have a similar type of requirement in our project.

[jantoniucci]

Sadly, I resolved this requirement using HAR ( https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/HAR/Overview.html) archives :(

On Wed, 17 Oct 2018 at 11:49 Kanchan-Shagalolu notifications@github.com wrote:

Hi Team,

Any updates on the status of this to support this feature? We also have a similar type of requirement in our project.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/raml-org/raml-spec/issues/281#issuecomment-430558182, or mute the thread https://github.com/notifications/unsubscribe-auth/ABINq1FZUvg8_y4GhnCqftUtTRcnviN4ks5ulvwQgaJpZM4HrpxX .