I want to search (say) "accounts" based on "name" or "status".
So I would like to have two actions :
GET /persons/?q=name==Jea*
GET /persons/?q=status==locked
How can I document that ?
I tried an Action with multiples transactions :
### GET /accounts{?q}
+ Request by name
+Parameters
+q (required, FIQLQuery)
**Only name is supported**
+ Request by status
+Parameters
+q (required, FIQLQuery)
**Only status is supported**
But Apiary editor complains because :
I must provide a message-body for my GET requests:
Message-body asset is expected to be a pre-formatted code block, every of its line indented by exactly 8 spaces or 2 tabs.
The + Parameters block is not recognized :
Ignoring unrecognized block
Thanks a lot
i can make solution that works for me.
Try this API Blueprint:
FORMAT: 1A
# requestByname
## Accounts [/accounts/?{q,type}]
### GET
+ Parameters
+ q (required, FIQLQuery)
+ type (string, `name` or `status`)
+ Request Name (application/json)
+ Response 200
{"name": "test"}
+ Request Status (application/json)
+ Response 200
{"status": 200}
Related
I'm currently using the following. It works, but I'd like to bake it into one data structure. This means moving the status and title into the array somehow. Is this possible?
## Invalid Credentials Object (object)
+ status: 401 (number)
+ title: `Invalid Credentials`
## Invalid Credentials (object)
+ errors (array[Invalid Credentials Object])
I'd like it to somehow resemble:
## Invalid Credentials (object)
+ errors (array[
+ status: 401 (number)
+ title: `Invalid Credentials`
])
Could you not do something like;
# Invalid Credentials (object)
+ errors (array[
#error
+ status: 401 (number)
+ message: 'Invalid Credentials'
])
Of course that's assuming you can next objects within an array.
How can I use generic named type in my API Blueprint definition?
I try like this:
FORMAT: 1A HOST: http://test.com/
# API Blueprint testing.
## Resource [/resources]
### Action [GET]
+ Response 200 (application/json)
+ Attributes
+ decorated_person (Address Decorator(Person))
# Data Structures
## Person (object)
+ first_name
+ last_name
## Address Decorator (*T*)
+ address
But Apiary Editor give me the error:
base type 'Address Decorator(Person)' is not defined in the document
here is two problems. Address Decorator isn't base type for example object and in attributes you have to use Mixin or Nesting.
FORMAT: 1A
HOST: http://test.com/
# API Blueprint testing.
## Resource [/resources]
### Action [GET]
+ Response 200 (application/json)
+ Attributes
+ Include AddressDecorator
# Data Structures
## Person (object)
+ first_name
+ last_name
## AddressDecorator (object)
+ address
I'm using Dredd to test an API I have written. It works fine until I try to vary the action uri within a resource. When I have an action of the form
## Retrieve Task [GET /task/{id}]
it sends a request to Drakov with the ] appended. This Drakov server is running the blueprint document.
Drakov 0.1.16 Listening on port 8090
[LOG] GET /task/myid]
[LOG] DELETE /task/myid]
[LOG] GET /task/myid]
You can see this request has an extra ] on the end.
This is my blueprint. It is a subset of the example from the Api Blueprint examples:
FORMAT: 1A
# Advanced Action API
A resource action is – in fact – a state transition. This API example demonstrates an action - state transition - to another resource.
## API Blueprint
# Tasks [/tasks/tasks{?status,priority}]
+ Parameters
+ status `test` (string)
+ priority `1` (number)
## Retrieve Task [GET /task/{id}]
This is a state transition to another resource
+ Parameters
+ id: `myid` (string)
+ Response 200 (application/json)
{
"id": 123,
"name": "Go to gym",
"done": false,
"type": "task"
}
What am I doing wrong?
Your API Blueprint has multiple errors. For instance,
+ Parameters
+ status `test` (string)
+ priority `1` (number)
...should be:
+ Parameters
+ status: `test` (string)
+ priority: `1` (number)
Also, you are defining a resource Tasks with URI Template /tasks/tasks{?status,priority} and then you are trying to define a GET action for the resource with a different URI Template. That is confusing.
I tried to create a sample API Blueprint (saved as sample-blueprint.md) like this:
FORMAT: 1A
# My API
## Task [/task/{id}]
### Retrieve Task [GET]
+ Parameters
+ id: `123` (string)
+ Response 200 (application/json)
{
"id": 123,
"name": "Go to gym",
"done": false,
"type": "task"
}
Then I launched a Drakov server in one terminal like this:
drakov -f *.md
Then I tried to run Dredd:
dredd sample-blueprint.md http://localhost:3000
Everything passed correctly:
$ dredd sample-blueprint.md http://localhost:3000
info: Beginning Dredd testing...
pass: GET /task/123 duration: 42ms
complete: 1 passing, 0 failing, 0 errors, 0 skipped, 1 total
complete: Tests took 50ms
Is this something you originally wanted to achieve?
I was trying the apiblueprint to document the APIs but I am encountering an error (on line 31) that says "Dangling message-body asset, expected a pre-formatted code block, indent every of it's line by 8 spaces or 2 tabs". I started seeing this error only after I added the table of contents.
If I remove line (34) " ", then error is gone. May be I am missing something here or I may not be clear. Any help on it is appreciable. Thanks
Below is my sample markdown.
FORMAT: 1A
---
## [I. Introduction](#def-intro)
1. [Group 1](#def-g1)
1. [G1 Resource 1](#def-g1-res1)
2. [G1 Resource 2](#def-g1-res2)
2. [Group 2](#def-g2)
1. [G2 Resource 1](#def-g2-res1)
2. [G2 Resource 2](#def-g2-res2)
---
<a name="def-intro"> </a>
# I. Introduction
This is my test API
<a name="def-g1"> </a>
# 1. Group 1
This is group 1 API
<a name="def-g1-res1"> </a>
## 1. G1 Resource 1 [/g1api1]
### g1api1 [GET]
This is g1api1
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api1"
}
<a name="def-g1-res1"> </a>
## 2. G1 Resource 2 [/g1api2]
This is g1api2
### g1api2 [GET]
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api2"
}
One of your problems is using anchors, in particular the one right before:
2. G1 Resource 2 [/g1api2]
You don't need to do this. If you render your documentation without those anchors and look at the left hand column, you can click on the links there. You will notice the related fragment in the browser address bar. You can then just use these fragments in markdown links like:
FORMAT: 1A
# My Api
This is my test API
## Table of Contents
1. [Introduction Section](#introduction/introduction-section)
1. [Group 1](#reference/one)
1. [G1 Resource 1](#reference/one/resource-1)
2. [G1 Resource 2](#reference/one/resource-2)
## Introduction Section
Blah Blah
# Group One
This is group 1 API
## Resource 1 [/g1api1]
### g1api1 [GET]
This is g1api1
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api1"
}
## Resource 2 [/g1api2]
This is g1api2
### g1api2 [GET]
+ Response 200 (application/json)
{
"response": "ok",
"resource": "g1api2"
}
Also, it will help you to read: https://apiary.io/blueprint
You should not be putting numbers before the "Group" and "Resource" keywords as they must come first in defining those sections. Apiary will render short-cuts in the left column for you and as I said above you can re-use the associated fragments in your own markdown links per my example above.
To illustrate my problem, I made a condensed example from the Apiary.io blueprint tutorial.
FORMAT: 1A
# Gist Fox API
# Group Gist
Gist-related resources of *Gist Fox API*.
## Gists Collection [/gists{?since}]
### List All Gists [GET]
+ Parameters
+ since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned.
+ Response 200
{
items: []
}
### Create a Gist [POST]
To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist.
+ Request (application/json)
{
"description": "Description of Gist",
"content": "String content"
}
+ Response 201
{
}
Then in my apiary documentation I get the following:
GET /gists{?since}
POST /gists{?since}
However, for me it makes sense to have the since query parameter only for the GET request. Unfortunately I didn't find a way to achieve this result:
GET /gists{?since}
POST /gists
Is it something possible?
Update
(Thursday, 23 Oct 2014)
The fix has been deployed; could you please give it a try and let me know if everything works as expected?
The bad news
It is our (Apiary) bug and you're not doing anything wrong :-(
The good news
It is a known bug we are currently working on and it is going to be fixed with the end of this week (Sunday, 19 Oct 2014) :-)