I've written a small web service that was designed to be "curl-able", so it relies on application/x-www-form-urlencoded parameters in POST requests, e.g.:
curl http://api.example.com/ -d param1=foo -d param2=bar
I would like to document this service using Apiary, but I've been unable to figure out a way to provide structured documentation for these parameters. I can provide an example request like this...
+ Request (application/x-www-form-urlencoded)
param1=foo¶m2=bar
...but this doesn't allow me to provide documentation on the
individual parameters (and does not lend itself well to testing in the
apiary console, since it is unable to provide input fields for the
various parameters).
I've read through the api blueprint specification a few
times and I've been unable to find a good solution. Is there any way
to provide structured documentation for these parameters?
You can use Attributes for this type description.
FORMAT: 1A
HOST: http://api.example.com/
# Test attributes 1
## Create post [/]
### Create a Post [POST]
+ Attributes
+ param1: foo (string) - Foo param
+ param2: bar (string) - Bar param
+ Request (application/x-www-form-urlencoded)
+ Response 201
Related
I've been working with the API Blueprint format for designing an API and have had a lot of fun working with it. When I was declaring my data structures I came upon a code reuse or model reuse issue.
According to the documentation when declaring a Response it has to be done like this:
For example:
+ Request 200 (application/json)
However when multiple people work on the document I don't want to instruct them what return code to use since we have them defined and they're numbers so people forget them. So to avoid having to go back and forth, instead I made this with the idea that I can use/reference one of the properties:
# Data Structures
## HttpCode (object)
+ success: 200 - Request processed successfully
+ not_found: 404 - Content requested not found
+ forbidden: 403 - Access to content is forbidden
I would reference it as such:
+ Response (HttpCode.success) (application/json)
...
It obviously does not work and I cannot find anything that pertains to what I want to do in the docs. Maybe i've missed it.
So how do you do it? Is it possible?
Thanks!
This is not possible. Their representative in GitHub closed my issue.
https://github.com/apiaryio/api-blueprint/issues/411
Here's a snippet of my apib document.
Essentially, I want to be able to put additional descriptive information after the Request and Response sections, however this information is not rendered. Instead any further text under a new heading is interpreted as part of the response 200 section. I would like to be able to put a table in the Errors section, so this data would ideally be markdown rendered. Is this possible with aglio?
Thanks!
#### Rate Limiting
This endpoint allows 20 requests per hour.
+ Request (application/json)
+ Attributes (object)
+ id (number)
+ Response 200 (application/json)
+ Attributes (object)
+ status: success (string)
### Errors
Table of error codes
Cameron, this is only currently possible within the description section before the request/response pairs. For example:
## My Resource [/foo]
### My Action [GET]
#### Rate Limiting
This endpoint allows 20 requests per hour.
#### Errors
Table of error codes
+ Request (application/json)
+ Attributes (object)
+ id (number)
+ Response 200 (application/json)
+ Attributes (object)
+ status: success (string)
Alternatively, you could hard code this sort of information in a custom template which would give you full control over what goes where. The reason I say "hard code" is because the API Blueprint parser is seeing your text as belonging to the response rather than the action or example, and I can't modify that behavior within Aglio. You could open a ticket on the upstream API Blueprint repository to request such a feature or use the workaround above.
One last note - you can describe 400 and 500 level responses as request/response pairs. Since the request/response pairs are rendered in the order given in the document you can ensure the error examples show up last.
Is there a way (and does it make sense even) to have dynamical values for my request parameters (in my case POST application/x-www-form-urlencoded that has two parameters username and password) which can be altered based on some function or a returned value from the server from a previous request?
The motivation being that i have a register-new-user request which i run from time to time off apiary.io and unless i manually change the example value for the username i get a "use already exists" response instead of 201 i want (since this request was already run with the username in the example).
What i'd like to have instead is a value in the API documentation that will change on each execution of the API call (either using some random number there, or to be able to have it take a value returned from a previous request).
Is there anything you can suggest to solve my "user already exists" response for register-new-user API call?
Here is my current API documentation (the relevant part):
## Registration [/users.json]
The `/users.json` resource handles registration of new user
### Register a New Patient [POST]
Register a new patient action sends email and password and registers
the new user in case it doesn't already exist
+ Request (application/x-www-form-urlencoded)
+ Attributes (Test User)
+ Body
user[email]=username#example.com&user[password]=123456
+ Response 201 (application/json)
{
"id":500
}
# Data Structures
## Test User (object)
+ "user[email]" (string): "username#example.com" - user email
+ "user[password]" (string): "123456" - user password
Thanks in advance
You can partially simulate this in the Apiary mock server by passing a header in your call, for example:
Prefer: status=200
See https://help.apiary.io/tools/mock-server/#multiple-responses
In general the mock server is not yet flexible and programmable enough to fully do what you describe, for example conditionals, dynamic variables or random responses.
We are working on enhancing this. If you'd like you may comment here on your requirements:
https://github.com/apiaryio/api-blueprint/issues/58
Feel free to also ping us in Apiary (in-app chat) or on support#apiary.io.
Thanks
I am trying to use apiary.io to document a JSON-RPC based API. I can get the pages formatted, but console simply does not work.
With JSON-RPC you typically only have 1 URI, such is the case with our API. Because of this, when attempting to define the methods, the blueprint editor gives the warning
Action with method POST already defined...
I figured I could ignore this, but in the apiary console when testing it will only returns the example response for the first action defined. Does anyone have a work around for this?
From what I understand from JSON-RPC spec and examples, multiple requests and responses could work for you better than defining POST endpoints multiple times.
# My API
## JSON-RPC [/endpoint]
### Doing something [POST]
+ Request Sum of numbers (application/json-rpc)
{"method": "sum", "params": {"a":3, "b":4}, "id":0}
+ Response 200 (application/json-rpc)
{"result": 7, "error": null, "id": 0}
+ Request Posting a message (application/json-rpc)
{"method": "postMessage", "params": ["Hello all!"], "id": 99}
+ Response 200 (application/json-rpc)
{"result": 1, "error": null, "id": 99}
Cons: Your API will be squashed into one or two endpoints and individual requests won't be visible in ToC.
Pros: The request-response pairing logic in Apiary mock server will then allow you to use some strategies (also described on the page linked above) to invoke different response than just the first one. However, as these strategies work only (in the time of posting this answer) with headers or status codes and they do not inspect body of incoming request's payload, you probably still won't be able to easily distinguish between your requests in console.
Possible workaround would be to give extra headers to your requests, such as X-Request: 1, X-Request: 2, etc., so the mock server can distinguish between them and return you the right response.
You can use trick with anchor, unique fragment path in api endpoint url.
# Group Awesnome JSON-RPC API
## Entity A [/#A]
### Procedure A [POST]
### Procedure B [POST]
## Entity B [/#B]
### Procedure C [POST]
### Procedure D [POST]
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?
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.
Edit
The correct URI Template should be:
http://baasar.apiary-mock.com/user/{appId}/{userId}{?force}
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