apiaryio / api-blueprint Goto Github PK
View Code? Open in Web Editor NEWAPI Blueprint
Home Page: https://apiblueprint.org
License: MIT License
API Blueprint
Home Page: https://apiblueprint.org
License: MIT License
I'm getting "semantic issues" for a couple POST response bodies that have no body. Section 5.2 says the body is optional, so how do I make the message go away?
Example:
## /v1/contractUsageData/csv
### POST
does stuff
+ Request (application/x-www-form-urlencoded)
reportSources=blahblah
+ Response 200 (text/csv;charset=UTF-8)
+ Headers
Content-decomposition: attachment; fileName=usage_20130709141439.csv
On the apiblueprint.org site it says that the ruby binding is currently "in the making".
Is there a github project for this that can be followed? As a ruby guy I am naturally very interested in the binding.
(Oh how I dream of generating rspec request specs automatically based on an API blueprint)
Hi
I don't know if it is already possible as i could not find something in the examples/documentation.
Can a response be conditional based on a parameter value in the request?
e.g.
Name eq 'My Name'
Name ne 'My Name'
Name eq 'My Name'
Name ne 'My Name'
If it is not possible this would be a nice feature.
Cheers!
in one of our APIs we have a resource that is used differently in different groups of actions -- e.g. POST to the same resource with different request bodies depending on the group.
This appears to be disallowed -- at least in apiary.io it produces a semantic issue, but appears perfectly valid for REST.
Could the blueprint spec be modified to allow redefining a resource in separate groups?
I'm new to Apiary so I need to learn the syntax either way. However, the New API seems to be broken in the documentation view of Apiary, making it rather hard for me to troubleshoot and learn. That and I can't seem to find the Legacy docs?
Is this project still active? Seems like a great idea but I'm not getting any response via Intercom either.
I think it would be very beneficial to add a JSON Schema to the tutorial (https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md) to show how it can be used. Possibleyone of the last steps? (an "Advanced" section maybe?)
Provide the ability to define arbitrary payloads that can be referenced later (similar to the concept of resource object).
Parametric description of metadata fields. Refer to #26
Add the possibility to use Markdown links wherever an asset is expected (e.g. a payload body or schema).
Due to close to no usability, poor design and intended use-case covered by #47 the Headers section in Resource and Action section should be deprecated and removed in future revisions of API Blueprint
I'd love to have
+ Response (application/json)
[]
as a shortcut for
+ Response 200 (application/json)
[]
To be discussed: Inheritance of headers / responses / resources.
Describe URI query parameters globally, share amongst several resources
Provide the ability to define HTTP headers that can be referenced later.
Note: This can also be covered as "Global HTTP Headers".
Reformat the API Blueprint specification document so it serves information on sections in more structured, unified and easier to ready way.
Documentation of HTTP headers using syntax similar to URI parameters.
e.g.
+ Headers
+ Location (string, `/some/uri`) ... URI of the created user account
It would be quite useful to automatically add id
HTML attributes to resources when they are rendered as headers, and use them to generate Table of Contents, placing it at the very top or where a special TOC placeholder is added.
Does 1A support required/optional flags in schema specifications?
My specification is:
## Entities [/api/entities]
+ Model
+ Body
```
{
"entities": [
{
"id": "entity1",
"name": "Entity"
}
],
"total": 1
}
```
+ Schema
```
{
"title": "Entities Schema",
"type": "object",
"properties": {
"entities": {
"type": "array",
"items": {
"required": ["id"]
}
},
"total": {
"type": "integer"
}
}
}
```
Trying to validate this response with Dredd, and it says that name
is required and is missing. I've validated the schema against http://json-schema-validator.herokuapp.com/ and it's all clear, leading me to suspect that it's how I've written the schema.
Thanks in advance.
Identifiers limitations tend to feel way too restrictive.
Reduce the non allowed characters to minimum. This should allow use of unicode (national) characters in Resource and Action identifiers. Consider banning [
and ]
only.
Revisit keywords & naming used throughout API Blueprint.
Expression for user-specific tokens.
I have it in my head that query parameters are declared like
GET [/my/resource{?color,flavor,ethnicity}]
That works in the parser, but so also do some other arrangements, like
GET [/my/resource?{color,flavor,ethnicity}]
GET [/my/resource?color={color},flavor={flavor},ethnicity={ethnicity}]
I thought I had read the syntax specification, but can't now locate it.
Documentation of message-body attributes. Similar to URI parameters.
Also if possible it should be clearly differentiated between the URI parameters description and Body Parameters description. Current state with the parameters
section of a resource (action) might lead to confusion what parameters are discussed.
Hey,
I'm not sure if we can use the issue tracker here for improvement request. (sorry)
I have a case where I've got many informations for a http header, i.e. the Link
http header.
In this case, to improve readability in the edition mode, preview or raw display, it would be really nice if it can support multiline.
+ Headers
Link: </uri>;
rel="http://myschema.org/relation/resource";
title="My title",
</uri2>;
rel="http://myschema.org/relation/resource2";
title="My title 2",
</uri3>;
rel="http://myschema.org/relation/resource3";
title="My title 3",
At the moment, everything is inlined and it's really annoying.
Thank you for the awesome work.
Create a brief glossary of terms accompanying the API Blueprint specification.
Just an idea.
Now all blueprint files are superset of GitHub Flavored Markdown, so they're obviously quite well displayed on GitHub out of the box.
However, if direct support for API Blueprint was added to github/markup, it would be possible to display blueprint-specific parts (such as endpoints, etc.) nicer than now and blueprints would be even more something like first-class citizens here on GitHub.
Possible problems:
github/markup
are most likely binded by extensions and .md
are already binded to the pure Markdown parser (and having a different extension undermines some of the pros of being fully compatible with Markdown)Another idea I came up with is to ask GitHub whether they wouldn't like to bake the direct support in themselves (maybe after the API Blueprint earns notable traction). Then it could be implemented in a similar way as GeoJSON or 3D objects, I suppose.
Support for media types and content negotiation.
Many RESTful APIs support scopes for calls. In other words, you can't make a certain request or perform an action unless a client has been granted a certain scope. For example, using the "Gist Fox API,", you might need gist_write
access to Edit a Gist.
Is there any support planned for surfacing this sort of information?
Direct support for hypermedia and modeling actions & relations.
Revisit resource object concept and syntax as well as its referencing.
To be discussed: Additional syntax for pagination.
Various toolings might have a need for a tooling-specific metadata at different point in blueprint. A solution would be to add a syntax construct that would be expected wherever a Markdown formatted discussion is expected and that would provide (potentially recursive) "key: value" notation.
E.g.:
# API
API Description
+ Metadata
+ Key: `Value`
# Resource [/resource]
Resource Description
+ Metadata
+ Key: `Value`
+ Key2:
+ Key3: `Value`
Which would be reflected in AST like
_version: 1.0
metadata:
name: API
description: "API Description\n\n"
metadata:
key: Value
resourceGroups:
- name:
description:
metadata:
resources:
- name: Resource
description: "Resource Description \n\n"
metadata:
key: Value
key2:
key3: Value
uriTemplate: /resource
model:
parameters:
headers:
actions:
Support for multiple API blueprint files within one API.
Currently there is a semantic issue if Content-Type
header is used but the body is empty (it means missing definition too). There should be just warning for case that body was forgotten.
Example
+ Response 200 (text/plain)
+ Headers
Content-Encoding: none
Last-Modified: Wed, 26 Feb 2014 09:09:37 GMT
Direct support for API authentication.
Explore possible concept of data bags for HTTP messages / API Blueprint assets.
Hi,
the HTTP Methods LINK
(http://www.freesoft.org/CIE/RFC/2068/239.htm) and UNLINK
(http://www.freesoft.org/CIE/RFC/2068/240.htm) are missing from the specification.
What are the reasons for this? Or just simply forgotten?
I played around with the official sublime plugin but found it wasn't really what I needed, so I tossed a linter together for SublimeLinter.
The file is https://gist.github.com/WMeldon/7988517 and you can add it by following these instructions. Not an ideal approach but it works for now. It annotates warnings and errors for, but there is no line info on the error message from Snowcrash yet so it just tosses it on top. (Better errors from Snowcrash would be great too :D)
Figured it might be helpful to someone, feedback welcome. I'm trying to build out a better toolset for writing docs and will contribute anything else I end up tossing together.
I know it's common amongst many API's to use PUT
as the request-mechanism to do updates on a record, but according to w3c PUT
will replace the record, PATCH
is the appropriate request-verb to use in the situation where you'd like to patch/update a record.
Hi folks,
I'd be very keen to contribute to a Java binding for snowcrash or otherwise assist with a Java-based Markdown Blueprint -> AST parser. Having read around, it seems like building a parser based on code that's not Sundown is not the way to go, given the API Blueprint extensions to that codebase, so it would seem a pure Java toolchain is out of the question.
Having read https://github.com/apiaryio/snowcrash/wiki/Writing-a-binding I have found that there isn't enough for me to make a start on a Java binding, so I would appreciate someone providing some architectural guidance or suggestions about how to do this.
Full disclosure: I'm the author of the open source Java Mock Server mentioned on the apiblueprint.org site (https://bitbucket.org/outofcoffee/api-blueprint-mockserver) and would ideally like to use the Java parser to support some of the proposed features in that project.
Thoughts/comments welcome.
All the best,
Pete
We have an API that provides two roughly equivalent forms for POST to the same URL. The key difference is the Content-Type: of the request: it accepts either application/json or text/dns (RFC-4207). The two request forms are closely related, but it would be an exaggeration to say they're merely direct translations one of the other.
Legacy Blueprint allows us to say this. The FORMAT:1A editor ignores it (only displays one of the two).
Is there some way I can achieve this?
Revisit proposed URI and Body parameters syntax.
Difference of the name throughout the document...
Introducing the API Blueprint Object Trait. Addressing following milestones:
Full implementation of traits assume following issues are implemented:
Trait is a quality or characteristic of an API Blueprint object (hereafter just object). At the moment the following sections of API Blueprint are recognized as API Blueprint object:
Traits can be used add additional semantics or a set of characteristics to an object.
A semantic traits adds a semantic meaning to an object.
Definition of a semantic trait:
# My API
+ Trait A ... Object Quality "A"
Referencing a defined trait:
## Resource 1 [/1]
+ Traits
+ [A][]
In-place definition & use of a semantic trait:
## Resource 1 [/1]
+ Traits
+ A ... Object Quality "A"
NOTE: Traits defined in-place cannot be referenced later
An object can reference multiple traits:
## Resource 1 [/1]
+ Traits
+ [A][]
+ [B][]
+ C ... Object Quality "C"
+ Type = `safe`
In addition to its semantic meaning a trait can also express certain characteristic of object's payload(s).
Where payload characteristic is one of:
For example:
# My API
+ Trait Color
+ Response Headers
+ X-Resource-Color (string, `red`) ... Color of the resource.
## Resource 1 [/1]
+ Traits
+ [Color][]
One trait can also represent a set of object characteristics:
# My API
+ Trait Art
+ Headers
+ X-Resource-Color (optional, string, `red`) ... Color of the resource
+ Properties
+ size = `42` (number) ... The size of an object
## Resource 1 [/1]
+ Traits
+ [Art][]
For more examples see https://gist.github.com/zdne/01e287fe18d232672d43
Consider the example from the Gist API:
## Gists Collection [/gists{?since}]
Collection of all Gists.
### 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
### 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)
+ Response 201 (application/hal+json)
Since the POST description is under the collection /gists{?since}
, it implies that there is a parameter for the post request that doesn't actually exist. This is parsed weirdly on apiary:
, and throws warnings for undefined parameters when using protagonist.
I think a simple solution would be to simply allow overriding the URI further down the tree. Something like this:
## Gists Collection [/gists]
Collection of all Gists.
### List All Gists [GET /gists{?since}]
+ 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
### 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)
+ Response 201 (application/hal+json)
RE: the tweet I sent to @apiblueprint and with @zdne.
We're currently documenting an API which takes POST params of the form:
some_object: {
a_required_field: {},
an_optional_field: {},
perhaps_an_object: {
a_nested_nested_field: {}
},
},
some_other_object: {
a_required_field: {},
another_required_field: {},
further_required_field: {},
},
etc..
and we'd love to see the ability to represent this nesting of parameters, or even describing of an object's optional/required parameters in the Blueprint spec.
I envisage it may look something like:
+ Parameters
+ currency (optional, string, `` ) ... A standard currency
+ merchant (required, merchant, `` ) ... A merchant object
+ reference_number (required, string, `` ) ... A merchant's external reference number
+ name (optional, string, ``) ... A merchant's full name
+ product (required, product, `` ) ... A product object
+ code (required, string, `` ) ... A product code
Or perhaps it could take the form:
+ Parameters
+ currency (optional, string, `` ) ... A standard currency
+ merchant (required, merchant, `` ) ... A merchant object
+ Parameters
+ reference_number (required, string, `` ) ... A merchant's external reference number
+ name (optional, string, ``) ... A merchant's full name
+ product (required, product, `` ) ... A product object
+ Parameters
+ code (required, string, `` ) ... A product code
I think the first option would be a lot cleaner.
Are there any plans on implementing something along these lines? Or how would we go about getting that in motion?
Cheers,
Jason
To be discussed.
If I'm using controllers as groups, it would be helpful to be able to specify the controller's path in the group specification and have that apply to all resources within the group.
For instance, instead of this:
# Group Users
## Login [/users/login]
## Logout [/users/logout]
I can do this:
# Group Users [/users]
## Login [/login]
## Logout [/logout]
In the same way that specifying myhost/api
in the HOST:
metadata applies /api
to the start of all URIs.
Mission: Test backend responses against what is defined in a blueprint. This is the blueprint validation.
With API Blueprint in CI the goal is to minimize number of ambiguous transactions in blueprint and support complex tests using scenarios.
An HTTP transaction to be tested. All the data needed to complete an HTTP transaction. A Well-defined Transaction.
A scenario is a sequence of steps. Where a step is either another scenario, a test case or a freeform text.
A setup block referencing a scenario.
An implicit test case is a test case created as a by-product of API Blueprint reference style description of an API.
Can an API blueprint be, by default, composed of implicit test cases or do they need to be explicitly stated?
Parameters of an HTTP Request
Ambiguous Transactions
A transaction with multiple defined responses.
Stateful Server
Possible need for some sort of set-up or ordering of test cases
Proposed steps to resolve collision points:
Parameters of an HTTP Request
Parser warnings, when there is no example in parameter's description.
HTTP-message headers and a message-body properties are already addressed by API Blueprint specification-by example.
Ambiguous Transactions
Parser warnings + introducing possible
keyword to denote a response that shouldn't be tested.
E.g.:
+ Response 201
+ Possible Response 401
+ Possible Response 503
Inside out approach where somebody writes tests for an API and the reference-style documentation is the by-product.
A scenario written after your API is described in an API blueprint. References to test cases and / or resources and actions.
A freetext scenario. A scenario discussing and API and thus implicitly describing the API.
A technicality, a reference to another scenario.
# Scenario A
...
# Scenario B
...
# My Resource [/resource]
## Retrieve [GET]
### Transaction Example 1
+ Background [Scenario A][]
+ Request A
+ Response 200
+ Possible Response 200
+ Possible Response 200
### Transaction Example 2
+ Background [Scenario B][]
+ Request B
+ Response 200
As of API Blueprint Format 1A the API Blueprint support "under the hood" transactions examples. With implicit "pairing" planned in its parser.
The upcoming API Blueprint revision should consider introducing explicit support for defining transaction.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.