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.
Related
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
As always, thanks in advance. You're all awesome, just for reading this.
I use Parse as my backend, and am using Stripe as my payment API. Parse has some stripe integration, but not the full API, so to access parts of the API that aren't built in to Parse, you have to use http requests.
I'm adding coupon functionality to my app, and therefore, sometimes will need to generate a transfer directly to my Stripe managed accounts, since the customer may have paid less than the recipient needs to receive. here is the cURL code, found in Stripe's API documentation, that I need to convert to an http request:
curl https://api.stripe.com/v1/transfers \
-u [secret api key]: \
-d amount=400 \
-d destination=[account id]
"Transfer to test#example.com"
Here is the Parse.Cloud.httpRequest I am using in my code:
Parse.Cloud.httpRequest
(
{
method:"POST",
url: "https://" + STRIPE_SECRET_KEY + ':#' + STRIPE_API_BASE_URL + "/transfers?amount=" + amountOwedProvider.toString() + "&destination=" + recipient_id
}
);
STRIPE_API_BASE_URL is 'api.stripe.com/v1'
amountOwedProvider is the number, in cents, that I still need to send the provider
recipient_id is a properly formatted stripe recipient id. I also use it when generating the initial charges.
When I make this request, the following error appears in my Stripe log:
"Unrecognized request URL (POST: /v1/transfers)
I have tried using both transfer and transfers, even though the documentation calls for transfers. I have also tried using transfers/?amount... rather than transfers?amount, but received the same error.
Any tips on how to properly create this http request? I'd really appreciate any guidance.
Thanks,
Jake
I'm an idiot. I started from the cURL request found here: https://stripe.com/docs/connect/special-case-transfers
You may notice that it does not have the currency parameter found in the actual code from the api documentation link I posted in my question. Turns out, it's a required parameter. I figured since it wasn't in this link, which I found first, that it was an optional parameter, and that if it wasn't specified, the default currency would be used. WRONG. i just had to add currency=usd into my request url. My final request looks like this:
Parse.Cloud.httpRequest
(
{
method:"POST",
url: "https://" + STRIPE_SECRET_KEY + ':#' + STRIPE_API_BASE_URL + "/transfers?currency=usd&amount=" + amountOwedProvider.toString() + "&destination=" + recipient_id
}
);
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
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