When writing an API-Deocumentation for an rest-service I came across an problem where I wanted to list all the possible Values which could be returned as a response.
In the case below it would be the "state" field which could contain any possible value of a enumeration and I wanted to sum up which possible states there are.
I could not find an easy and nice way to do it with apiblueprint. Is there a way to display sections collapsed by default and expand them when additional information is needed?
Here is the Sample code I have:
## Sample [/Sample?{id}]
Get all the information for the sample
+ Parameters
+ id = `0` (Integer, optional) ... The Id of the resource to get
+ Model (application/json)
+ Body
{
"name": "Name of the Resource",
"state": "deleted"
}
### Retrieve the sample data of the system [GET]
+ Response 200
[ProviderConfiguration][]
I need something like "Values" for the parameters section but for the Body part to describe the state in the Body section e.g.
<collapsible>
+ state (EnumType) ... current state of the sample object
+ Values
+ `active`
+ `inactive`
+ `deleted`
</collapsible>
Unfortunately, this is not yet possible with API Blueprint. However, it's planned - see https://github.com/apiaryio/api-blueprint/issues/25 and https://github.com/apiaryio/mson.
Related
I have an API get requests in Postman that uses a data file of voucher codes to look up other information about the code, such as the name of the product the code is for. When using collection runner the voucher codes are passed incorrectly and the data is returned about the product.
For some reason, I'm unable to capture the data from the response body and link this into the next request.
1st get request has this in the body section:
{
"dealId": 6490121,
"voucherCode": "J87CM9-5PV33M",
"productId": 520846,
"productTitle": "A Book",
"orderNumber": 23586548,
"paymentMethod": "Braintree",
"deliveryNotificationAvailable": true
}
I have this in the tests section to capture the values:
var jsonData = pm.response.json()
pm.environment.set("dealId", jsonData.dealId);
pm.globals.set("productId", jsonData.productId);
when posting the next request in the body:
{
"dealId":{{dealId}},
"dealVoucherProductId": {{productId}},
"voucherCode":"{{VoucherCode}}",
}
and pre-request scripts:
pm.environment.set("productId", "productId");
pm.globals.set("dealId", "dealId");
As you can see I've tried to use global and environmental variables both are not populating the next request body.
What am I missing?
This wouldn't set anything in those variables apart from the strings that you've added.
pm.environment.set("dealId", "dealId");
pm.globals.set("productId", "productId");
In order to capture the response data and set it in the variable you will need to add something like this to the first requests Tests tab:
var jsonData = pm.response.json()
pm.environment.set("dealId", jsonData.dealId);
pm.globals.set("productId", jsonData.productId);
Depending on the response schema of the first request - This should set those values as the variables.
You can just use the {{dealId}} and {{productId}} where ever you need them after that.
If you're using a environment variable, ensure that you have created an file for those values to be set.
In my blueprint I'm defining a data structure and try to use it like so
+ Attributes
+ error: (Error Details, required)
Data structure definition at the end of the document:
# Data Structures
## Error Details
+ code : 1234 (number, required) - see list of error codes
+ message: User not found (string, required) - a human-readable error message
The resulting sample response body looks just like expected but the validation on apiary.io shows semantic issues for each of the places where I use constructs like this, saying "No value(s) specified".
Am I doing something wrong or is it a problem with the apiary.io parser?
I had the same problem and solved it by
omitting the colon
separating the object definition and type (see owner in this example):
Company (object)
name: Company name (string)
owner (OwnerResponse) (object)
A similar answer to other current answers, but none the less this fixed it for me.
No good:
+ Attributes
+ `status`: OK
+ `data`:
+ 5 (Channeldata)
+ 7 (Channeldata)
Fix:
+ Attributes
+ `status`: OK
+ `data`
+ 5 (Channeldata)
+ 7 (Channeldata)
As others have noted, losing a colon in the right place can fix things.
Attribute section can be also defined as + Attributes <Type Definition> (specification), so defining + Attributes (Error Details, required) should fix the given semantic issue.
Edit:
You have to omit a colon between attribute's name and its type, when an example value is not defined:
+ Attributes
+ error (Error Details, required)
Missed that before, sorry.
Consider this excerpt from https://github.com/apiaryio/mson#example-1 ...
Example 1
A simple object structure and its associated JSON expression.
MSON
- id: 1
- name: A green door
- price: 12.50
- tags: home, green
Let's say I would like to define valid values for the name attribute. Consider a context of API testing with a tool such as Dredd. We may need to define what are the expected/valid name values in response to GET'ing this resource, or else something is probably broken and this test step should fail.
And/or, if creating/updating a resource of this type, we may need to define what name values are valid/accepted. Is this currently possible to define in MSON?
(I believe this can be done in a JSON schema, which makes me hopeful for MSON support.)
Following is an example API Blueprint resource to illustrate how this would be used...
# Thing ID [/api/thing/id]
# List Thing ID attributes [GET]
+ Response 200
+ Attributes
+ href (string)
+ make (string)
+ model (string)
+ version (string)
+ Body
{"href":"/api/thing/id","make":"BrandX","model":"SuperThingy","version":"10.1"}
In the above example, there are 3 known/accepted/valid values for the model attribute: CoolThingy, AwesomeThingy, and MLGThingy
Can we represent this resource in MSON, such that...
Apiary (or other rendered) API documentation consumers can easily know what model values to expect?
Dredd processes and passes/fails the model value in the response to a GET to this resource?
In MSON you can use enum, see the example below.
name (enum[string])
joe (default)
ben
mark
I'm documenting a public API that has a method named /findGuild that takes a mandatory key parameter and one of the following parameters:
byPlayer
byName
It must have either byPlayer or byName; My question is: How do I indicate that byPlayer and byName are mutually exclusive, but one is mandatory?
Right now, I have the following in my .apib for this Resource:
### GET /findGuild{?byName,byPlayer,key}
+ Parameters
+ byName: `YourGuild` (string, optional) - Search for the Guild by its name.
+ byPlayer: (string, optional) - Search for Guild by a player. Does not seem to work.
+ key: `ffffffff-ffff-ffff-ffff-ffffffffffff` (string, required) - The user's API key.
+ Response 200 (application/json)
+ Attributes (object)
+ guild (string) - The guild id or null.
+ success (boolean) - Should be true.
+ Body
{
"guild": "ffffffffffffffffffffffff",
"success": true
}
I am afraid (but not totally sure) API Blueprint is not capable of expressing this kind of relationship at the moment.
What I can surely tell you is that, according to public roadmap, URI Parameters will be replaced with an MSON object, which supports the scenario you're asking for.
Hope it helps!
How can I get the optional result data values from the Steam Web API?
For example, from GetPlayerAchievements I also want the name and description.
So far I use this URL: http://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v0001/?appid=MYAPPID&key=MYKEY&steamid=MYSTEAMID
You need to add &l=en to the end of your URL. This adds the language dependent fields of name and description to the results.
en can be substituted for other supported languages
Example for a player's Team Fortress 2 stats:
URL: http://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v0001/?appid=MYAPPID&key=MYKEY&steamid=MYSTEAMID&l=en
Returns a JSON result that has this block in the ['playerstats']['achievements'] array
{
"apiname": "TF_PLAY_GAME_EVERYCLASS",
"achieved": 1,
"name": "Head of the Class",
"description": "Play a complete round with every class."
}