Api-blueprint: Multiple requests and responses with same status code and different parameters

[netmilk]

At this moment API blueprint does not support multiple examples (request and response pairs) for invoking different behavior on same action with same status code for testing and specifying non optimistic or corner API behavior. For full support of this feature in blueprint we need at least one of following blueprint extensions:

• Possibility to specify parameters for both request and response.
• Multiple named examples under one resource action (explicit pairs?)
• Non-unique status codes for responses (or distinguished by name)

Example:

# Machine member [/machines{/id}{?fields}]

+ Parameters
  + id (required, number, `1`) ... Machine identificator
  + fields (optional, string) ... Comma separated list of fields included in response
  + include (optional, stirng) ... Comma separated list of embedded relate objects

## Retreive a machine [GET]

+ Response (200)

    {
      "name": "waldo",
      "type": "bulldozer",
      "createdAt": "Wed Oct 27 16:32:27 CET 2014"
    }


+ Response filtered parameters (200)
  + Parameters
    + fields = `name`

  + Body
        {
          "name": "waldo"
        }  

+ Response embedded objects (200)
  + Parameters
    + fields = `name`
    + include = `owner, type`

  + Body
        {
          "name": "waldo'
          "type": {
            "name": "buldozer"
          },
          "owner": {
            "nane": "Adam Kliment",
            "nick": "netmilk"
          }
        }

+ Response (404)
  + Parameters
    + id = `999`

  + Body
            {
              "message": "Document not found"
            }

As a workaround in Dredd, I propose to allow user be able to programatically create new named transaction example under same resource action in the AST. Action will be flagged in the AST and it will be highlighted in Dredd results to distinguish between actions is coming from AST and manually created.

ast = require 'ast'

ast.newExample "Machines > Machine > Update a Machine", "New example name", (newExample) ->
    newExample.parameters = 
      id: 2000

    newExample.request =
      headers:
        "Content-Type": 'application/json'
      body: "{ \"name\": \"waldo\"}"

    newExample.response =
      status: 400
      headers:
        "Content-Type": 'applicaiton/json'
      body: "{ \"message\": \"Rejected, can't update name\"}"

Or user will can be allowed to load data stored in another blueprint:

ast.newExample "Machines > Machine > Update a Machine", "New example name", (newExample) ->
  ast.newExample = loadFromBlueprint "./storage/bad_params.md" "Machines > Machine > Update a Machine with invalid data"

[zdne]

@netmilk I would say

Possibility to specify parameters for both request and response.

Assuming implicit request pairs, I am not sure why you need it for response (as that is associated with the request), how this would be different to https://github.com/apiaryio/api-blueprint/issues/58#issuecomment-34958639

[akiran]

+1 Looking forward to use this feature

[mehradh]

+1 We need this too

[galindale]

+1 great

[fosrias]

@netmilk Frankly, I think this could all go a step further in the blueprint by putting an absolute (non-tempated) URI on a request element and being able to access the associated response by calling that URI. Further, it would be nice to tag those responses and be able to access them by tag in say the machine column with a selector. This idea overlaps with another issue I have noted this possibility on that @zdne could cross-reference here if appropriate.

[zdne]

@fosrias would you mind sketching a pseudo example of your proposal (of using an URI instance).

Re tags – I would try to not tie this one to another feature unless it does not make sense without it.

[ThaNarie]

+1 Would love to see this implemented!

With a basic resource collection that supports pagination, searching, sorting and filtering on 'published':

## Items Collection [/items{?limit}{?since}{?until}{?q}{?sort}{?published}]

There is no way to have different examples for only search, or only sort, or only filter.

Currently the parameters are scoped to an action (e.g. [GET]), but they should be scoped to a request (or an example of they encapsulate a request+response pair).
Query parameters don't make up a different resource, they show a different representation (or slice) of a resource, thus is as much part of a request as the request body itself.

The current workaround is to create 4 different resource collections, each have their own [GET] and unique parameters, just to have them show up as different testable actions.

[zdne]

Hey @ThaNarie

thanks for feedback! This is definitely a planned feature – #58 – we should be able to define transaction examples based on parameters' value.

Note the /items{?limit}{?since}{?until}{?q}{?sort}{?published} isn't a valid URI template (correct should be something like /items{?limit,since,until,q,sort,published}

[ThaNarie]

Hey @zdne,

Thanks, looking forward to it!

I did indeed notice the shorter variant, although they seem to work both I did already changed it to the shorter version :)

[zdne]

You are right – the longer version is technically correct as well.

[gagle]

+1

[vivin]

+1

[kirkstrobeck]

+1

[zdne]

@netmilk

• Possibility to specify parameters for both request and response.

Closing this one as duplicate to #58 .

• Multiple named examples under one resource action (explicit pairs?)

You can already name requests, please let me know if it is not sufficient.

• Non-unique status codes for responses (or distinguished by name)

You can already have multiple responses with same status codes, let me know if this is not sufficient.

---

@fosrias

Frankly, I think this could all go a step further in the blueprint by putting an absolute (non-tempated) URI on a request element and being able to access the associated response by calling that URI

I like it. Should we move this feature request to #58 ?

[fosrias]

@zdne Yes. Feel free to move it there.

[netmilk]

@zdne All my motivation for this issue was invoking different responses with different request URI parameters under one action and it's satisfied in #58.
Thanks.

[sajadabasi]

now can we use this ? if yes how ?

[hypeofpipe]

☝️