Aglio Render Markdown after Request / Response section - apiblueprint

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.

Related

I am getting false in API query with code 200 with ruby

Friends, I can't understand what's going on, I'm new to programming.
#Create Employee
#manter_user = Crud.new (my class)
#Create
$response = #manter_user.create(my method)
puts "Response is: #{$response}"
puts "Create Response HTTP code 200: #{$response.code == 200}"
end
crete ok
Response is: {"status":"success","data":{"name":"Kip","salary":8037.4700000000002546585164964199066162109375,"age":63,"id":7435},"message":"Successfully! Record has been added."}
**Create Response HTTP code 200: true**
#list
#id = $response.parsed_response["data"]["id"]
puts "#id: #{#id} retornado é o mesmo préviamente criado..."
retrieve_response = #manter_user.retrieve(#id)
puts "Retrieve Response HTTP code 200: #{retrieve_response.code == 200}"
end
List
**Retrieve Response HTTP code 200: false**
As I mentioned in my previous Answer and the comments below.
The dummy API you are using does not actually store the records you are creating it just provides a dummy response.
These are fake online REST APIs for testing and prototyping sample applications that use rest calls to display listings and crud features. This rest api tutorials, faking a server, and sharing code examples can all be used.
Methods provided by the API:
Create - You can "create" a record and receive a fictional response but the record is not persisted.
{"status":"success","data":{"name":"Alva","salary":12,"age":33,"id":1488},"message":"Successfully! Record has been added."}
Retrieve an individual record - You can retrieve a single record up to id 24 (a fixed list of records are available). Response differs from other methods. (This will result in a failure of verifying a 200 HTTP status code if you use an id > 24, which would be the case if you are using the id from the previously created record (also see below for another reason))
{"status"=>"success", "data"=>{"id"=>9, "employee_name"=>"Colleen Hurst", "employee_salary"=>205500, "employee_age"=>39, "profile_image"=>""}, "message"=>"Successfully! Record has been fetched."}
Update - You can "update" a record with any id and receive a fictional response but the response is malformed JSON making it effectively useless.
{"status"=>"success", "data"=>{"{\"name\":\"Cassia\",\"salary\":\"100000\",\"age\":\"24\"}"=>nil}, "message"=>"Successfully! Record has been updated."}
Delete - You can "delete" a record with any id and receive a fictional response.
{"status"=>"success", "data"=>"78", "message"=>"Successfully! Record has been deleted"}
There is no way using this dummy API that you can actually test the full lifecycle of record due to the way it is constructed.
Additionally it appears this API is in the process of being torn down:
They are trying to sell the domain and associated code
The page regularly shows that it is down, suspended, or under maintenance
They recently have implemented request throttling which is now resulting in a HTML response of "Too Many Requests" which will make it more difficult to use for basic testing. (This will also result in a failure if verifying a 200 HTTP code response)

Referencing a property inside a defined data structure in API Blueprint/MSON

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

Have Dynamical values for my parameters in the Request payload (POST x-www-form-urlencoded)

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

Is there any way to send empty optional query parameters?

I'm writing documentation for API, and got problem.
Here is link definition:
### Get hotels availability [GET /agent/v1/hotel/availability{?regions,hotels,from,to,limit,offset}]
Parameters:
+ Parameters
+ regions (required,string,`399,189`)
+ hotels (optional, string, `1844`)
+ from (optional, string, `2016-03-12`)
+ to (optional, string, `2016-03-19`)
+ limit (optional, number, `1`)
+ offset (optional, number, `0`)
When I'm trying to send request with empty hotels parameter for example, apiary uses 1844 instead of empty. If I'll try to example it to empty, hotels=hotels is sended.
Is there any way to send empty for optional parameter, or not send it at all?
Here is link with screenshot:
http://www.awesomescreenshot.com/image/1008356/09614be501945b0644fd84a06e311404
I'm not sure whether I understand your problem correctly. I tried to reproduce the behavior you described. I created a new API Project in Apiary and wrote following API Blueprint:
FORMAT: 1A
# Hotels API
# Group Hotels
## Hotels [/agent/v1/hotel/availability{?regions,hotels,from,to,limit,offset}]
+ Parameters
+ regions (required,string,`399,189`)
+ hotels (optional, string, `1844`)
+ from (optional, string, `2016-03-12`)
+ to (optional, string, `2016-03-19`)
+ limit (optional, number, `1`)
+ offset (optional, number, `0`)
### Get hotels availability [GET]
+ Response 200 (application/json)
{"hello":"world"}
Then I opened console pane in the generated interactive documentation and tried to edit URL parameters:
The URL at the top is changing correctly. I made some requests with the Console and the Traffic Inspector page seems to confirm that correct parameters has been sent:
I think you'll have to refine your question and provide more information. Also, I believe this is fairly Apiary-specific topic and it may make more sense to contact Apiary Support at support#apiary.io instead. If e-mail isn't your thing, there's also an interactive chat:
Disclaimer: At the time of writing the answer I work for Apiary.

How to specify error codes in Apiary Documentation?

I want to specify the various exceptions/errors that have to be returned while making an API call. How do I achieve this with Apiary.
Kyle's response is indeed correct. I will just add that if you want to add little bit more semantics to this you can write the other possible responses like this:
## POST /users/resendVerification/{userId}
Resends the user's verification code to the email address on record.
+ Response 201
+ Response 403
Returned if the user does not have access to the requested account
+ Body
+ Response 404
Returned if a user was not found for the given userId
+ Body
Note: The + Body is needed (even though it is empty) to distinguish the description from a message-body.
I'm not aware of a specific syntax for error codes. In the past I've simply used bullet points. For example, this is my code for a re-request verification code API.
## POST /users/resendVerification/{userId}
Resends the user's verification code to the email address on record.</br>
• 403 is returned if the user does not have access to the requested account</br>
• 404 is returned if a user was not found for the given userId</br>
+ Response 201
Hope that helps.

Resources