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
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.
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.
I'm experimenting with grape and Ruby by trying to make a Yo API callback function.
I can get simple examples up and running like this . . .
resource :loc do
get ':loc' do
params.to_yaml
end
end
How would I go about extracting username and x and y coordinates into separate ruby variable given a callback with the following format?
http://yourcallbackurl.com/yourendpoint?username=THEYOER&location=42.360091;-71.094159
When the location data is screwed up . . .
--- !ruby/hash:Hashie::Mash
username: sfsdfsdf
location: '42.360091'
"-71.094159":
route_info: !ruby/object:Grape::Route
options:
:prefix:
:version: v1
:namespace: "/loc"
:method: GET
:path: "/:version/loc/:loc(.:format)"
:params:
loc: ''
:compiled: !ruby/regexp /\A\/(?<version>v1)\/loc\/(?<loc>[^\/.?]+)(?:\.(?<format>[^\/.?]+))?\Z/
version: v1
loc: toto
format: txt
This is how Rack::Utils works. Default params separators are "&" and ";" (its totally legal according to HTTP standard). So you have to parse query string by yourself here.
location = Rack::Utils.parse_nested_query(env['QUERY_STRING'], '&')['location']
coordinates = location.split(';')
UPD: typo with hash key fixed.
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}