Documenting query parameters with API Blueprint

Question

I'm trying to document a query parameter in API Blueprint, but I'm not entirely sure if I have done it correctly. The resource looks like this:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}

That request would deactivate the user while the following would delete the user object:

DELETE http://baasar.apiary-mock.com/user/{appId}/{userId}?force=true

This is the Blueprint markdown I have for this:

## User [/user/{appId}/{userId}]
Handle user objects

+ Parameters
    + appId (required, number, `1`) ... Application ID (`appId`)
    + userId (required, number, `1`) ... Numeric `userId` of the User object to manage

### Remove an User [DELETE]
+ Parameters
    + force (optional, boolean, `false`) ... Set to `true` to remove instead of deactivate

+ Response 204

However, when rendering this with Apiary I only see force in the list of parameters, but it is now shown in the example URL. Is that just me misunderstanding the GUI or should query parameters be documented in another way?

score 19 · Accepted Answer · edited Jun 24 '14 at 18:17

19

Your blueprint is perfectly fine, the problem is that the current Apiary documentation does not handle URI parameters correctly.

Could you please try the new documentation out? It should handle URI parameters properly.

URI Parameters

Edit

The correct URI Template should be:

http://baasar.apiary-mock.com/user/{appId}/{userId}{?force}

edited Jun 24 '14 at 18:17

Zdenek

3,523
25
34

answered Apr 03 '14 at 18:28

Baggz

16,239
4
35
25

Thank you very much for your answer. I should have said that I use the new docs already. What confuses me is that there is no separation between "resource parameters" and "action parameters". So I think that it is not clear where to put `force` in the above example. – Sebastian Dahlgren Apr 04 '14 at 06:25
2

I have changed my resource definition to look like this `## User [/user/{appId}/{userId}?{force}=bool]` (I get an error in the Apiary syntax if `force` isn't present). That looks really good for the `DELETE` verb, but it makes my `GET` verb in the same resource look odd, as it does not support the `force` parameter. – Sebastian Dahlgren Apr 04 '14 at 07:18
1

You can see the desired behavior here with "list all notes" and "create note": http://docs.queryparameters.apiary.io/?3ColumnDocumentation=1 There's just no documentation supporting the new URI template behavior, so no one knows how to use it. :-/ – James H Apr 08 '14 at 19:47
Fair point @james-h; I will add it to the specification https://github.com/apiaryio/api-blueprint/issues/79 – Zdenek Apr 15 '14 at 13:12
@Baggz Off topic, but what theme is that? – Dees Oomens Apr 25 '17 at 11:31
@DeesOomens it's the 'documentation' view in Apiary – csilk Oct 11 '17 at 00:44

score 1 · Answer 2 · answered Oct 30 '17 at 07:14

My curl request:

curl -k -u username:password https://api.techie8.io/api/1.0/bits?bit_type=1

Apiary blueprint:

## Bits Collection [/bits?bit_type={bit_type}]

### List Latest bits [GET]

List all bits recently inserted into database.

+ Parameters
    + bit_type (number, optional, `1`) ... Type of bit to retrieve: 1: Bits, 2: Newsletter

Documenting query parameters with API Blueprint

2 Answers2

Edit

Linked