Group action request and response by name for different expectations

[stekycz]

There is a way to name multiple requests in API Blueprint (mentioned in #55) however there is no way how to specify which response is expected for given request. I understand that it is only an example of request or response but without knowledge of relations between these I am confused reading multiple requests and responses for one resource. I do not want to specify all cases (for that purpose there should be specific testing tool for API). I want to keep request related with its response.

Let`s say I want to write documentation of request not only for correct request but also show an example of bad request which expects 404 status code. Currently I can write something like

+ Request
+ Response 200
+ Request Not Modified
+ Response 304
+ Request Bad Request
+ Response 404

and the documentation show it as

+ Request
+ Request Not Modified
+ Request Bad Request
+ Response 200
+ Response 304
+ Response 404

Name of request is also visible only in new documentation design which is confusing in current (older) version of design.

I can assume that the order of requests and responses are in sync but I have to scroll to find related information. Yes, it is problem of documentation mostly but I think these cases could be grouped also in AST.

[zdne]

Please refer to apiaryio/snowcrash#53 and Transaction example note on #21

[davidbarton]

@zdne I see apiaryio/snowcrash#53 is closed already. How about this one? I am still unable to pair request with possible responses based on headers.

Do you plan to include this type of requests (different headers) into Dredd testing? Is there some discussion about it already?

# Group Entities
## Entity [/entity]
### List all [GET]
+ Request
    + Headers

            x-api-versions: 0.1.7

+ Response 200 (application/json)
    + Headers

            x-api-versions-available: 0.2.1
            x-api-deprecated: true

    + Body

            [{
                "id": 8
            }]

+ Request
    + Headers

            x-api-versions: 0.2.1

+ Response 200 (application/json)
    + Body

            [{
                "id": 4
            }]

And output looks like this:

Request
x-api-versions: 0.1.7

Request
x-api-versions: 0.2.1

Response
200 (OK)
Content-Type: application/json
x-api-versions-available: 0.2.1
x-api-deprecated: true
[{
    "id": 8
}]

Response
200 (OK)
Content-Type: application/json
[{
    "id": 4
}]

Ps: example is Restify versioned API.

[zdne]

@davidbarton

I believe this is working as intended. The output for your blueprint with actual parser is:

_version: 2.0
metadata:
name:
description:
resourceGroups:
- name: "Entities"
  description:
  resources:
  - name: "Entity"
    description:
    uriTemplate: "/entity"
    model:
    parameters:
    actions:
    - name: "List all"
      description:
      method: "GET"
      parameters:
      examples:
      - name:
        description:
        requests:
        - name:
          description:
          headers:
          - name: "x-api-versions"
            value: "0.1.7"
          body:
          schema:
        responses:
        - name: "200"
          description:
          headers:
          - name: "Content-Type"
            value: "application/json"
          - name: "x-api-versions-available"
            value: "0.2.1"
          - name: "x-api-deprecated"
            value: "true"
          body: "[{\n    \"id\": 8\n}]\n"
          schema:
      - name:
        description:
        requests:
        - name:
          description:
          headers:
          - name: "x-api-versions"
            value: "0.2.1"
          body:
          schema:
        responses:
        - name: "200"
          description:
          headers:
          - name: "Content-Type"
            value: "application/json"
          body: "[{\n    \"id\": 4\n}]\n"
          schema:

Clearly the x-api-versions: 0.1.7 is paired with the "deprecated" response while the x-api-versions: 0.2.1 has the non-deprecated version.

Is that OK for you?

As for Dredd the multiple transaction examples should be eventually definitely supported. But please use Dredd issues for this. CC: @netmilk

[zdne]

@stekycz

I believe this was addressed in apiaryio/snowcrash#53 (Snow Crash v0.10.0). Closing this issue. Please comment & reopen if you think this is not yet addressed.

[zdne]

@stekycz @davidbarton for the record: As of now this is still not yet addressed in Apiary (as it was not yet updated to the latest Snow Crash); but it is fully implemented in the Snow Crash (and Protagonist).

[davidbarton]

Sorry I was referring to Apiary doc. So thanks a lot.