Api-blueprint: Need multiple actions of same HTTP verb on same resource (but different request content-type)

[jrep]

We have an API that provides two roughly equivalent forms for POST to the same URL. The key difference is the Content-Type: of the request: it accepts either application/json or text/dns (RFC-4207). The two request forms are closely related, but it would be an exaggeration to say they're merely direct translations one of the other.

Legacy Blueprint allows us to say this. The FORMAT:1A editor ignores it (only displays one of the two).

Is there some way I can achieve this?

[jrep]

Update: I find I can do this by only stating one response:

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

However, this doesn't display correctly in embedded mode (only shows one request type). Preview and Documentation views within the editor are good.

[zdne]

@jrep

This seem to be a lackluster in the current Apiary embed (design). I have notified @apiaryio team bout this problem.

[zdne]

@jrep is the request here (next to the limitation in embed) to support multiple responses?

If so following should be already valid:

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

[jrep]

Your example shows multiple requests but only a single response. That's just like my example. Yes, that is syntactically valid, but it is not able to express what we need to express.

Yes: the need here is to show a different "Response 200" for each request. The response content-type matches the request content-type (so two request content-types means two response content-types), but also the information in the two responses is not precisely equivalent.

With the Legacy format, we defined one request and its response, then the next request/response pair. That's a syntax error in the new format, and there doesn't seem to be any valid way to say this.

Update: Oops, I didn't look close enough: your example is different from mine in at least two ways: two responses, and use of named requests. Trying that now.

[zdne]

@jrep

I am not certain how do you mean it. Can you please submit here a snippet of the legacy blueprint?

[jrep]

Github ticket won't let me attach text. You can get the legacy blueprint from https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib

[zdne]

Got it

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

I think it is fundamentally OK to express this as:

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

This is a classic Content-Negotiation Example. Create a resource from many different representations while the response has no body and just states OK (and perhaps a link to it).

The content negotiation counterpart to this would be:

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

I think one body-less response to multiple requests that differs in content-type but have the same meaning (create a resource) is the good design. However I do want to lift this restriction (of warning when there are multiple responses with same status and content type) with the implementation of https://github.com/apiaryio/snowcrash/issues/53

[zdne]

@jrep This issue was addressed in https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0) therefore I am closing it. Please comment & reopen if needed.

[foxx]

Although an endpoint can have multiple transaction examples, as seen in apiaryio/snowcrash#53 these don't render out very cleanly in Apiary.

Take the following example...

You have /oauth2/authorize, which by specification will handle various different scenarios (such as getting an access token from refresh, or generating a token from password, etc). Having these merged into a single action on the API docs is very hard for the reader to understand, instead it's easier for the user to have multiple endpoints such as "Refresh access token" and "Authenticate User" in the side menu. However this is not possible because you cannot specify the same method/URL combination twice.

This is a prime example of where the API Specification is forcing its developers to use a certain approach and, in cases like the above, doesn't fit with common design patterns.

[vitaly-zdanevich]

I see incorrect syntax highlight - see the color of Body: