To be discussed: Additional syntax for pagination.

Parametric description of metadata fields. Refer to #26

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

API Blueprint & Testing

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.

Terms

Test Case

An HTTP transaction to be tested. All the data needed to complete an HTTP transaction. A Well-defined Transaction.

Scenario

A scenario is a sequence of steps. Where a step is either another scenario, a test case or a freeform text.

Background

A setup block referencing a scenario.

Test Case

Implicit Test Case

An implicit test case is a test case created as a by-product of API Blueprint reference style description of an API.

Question

Can an API blueprint be, by default, composed of implicit test cases or do they need to be explicitly stated?

Collision points

• Parameters of an HTTP Request

  • URI parameters
  • URI Query parameters
  • HTTP message headers
  • message-body properties

• Ambiguous Transactions

  A transaction with multiple defined responses.

• Stateful Server

  Possible need for some sort of set-up or ordering of test cases

Proposal

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

Explicit Test Case

Inside out approach where somebody writes tests for an API and the reference-style documentation is the by-product.

Scenario

Ad-hoc Scenario

A scenario written after your API is described in an API blueprint. References to test cases and / or resources and actions.

Scenario-driven Blueprint

A freetext scenario. A scenario discussing and API and thus implicitly describing the API.

Background

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

Notes

Transaction Example

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.

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)

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?)

Support for multiple API blueprint files within one API.

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?

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.

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:

Revisit resource object concept and syntax as well as its referencing.

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.

Provide a facility to embed an asset inside another asset while keeping the actual asset media-type opaque. For example re-use a message-body asset inside another message-body (e.g. an item inside its collection).

Possibly related issues:

• #9
• #25
• #28

To be discussed.

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.

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.

Documentation of HTTP headers using syntax similar to URI parameters.

e.g.

+ Headers
    + Location (string, `/some/uri`) ... URI of the created user account

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.

• Parameters
  • where (string, optional) ...
    • Values
      • Name eq 'My Name'
      • Name ne 'My Name'
• Response 200 (application/json) if Name eq 'My Name'
  response json x
• Response 200 (application/json) if Name ne 'My Name'
  response json y

If it is not possible this would be a nice feature.

Cheers!

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

Direct support for API authentication.

RFC proposals

• API Blueprint RFC 0002: Authentication Framework
• API Blueprint RFC 0003: Basic Authentication Scheme
• PR: OAuth 2 Authentication Scheme

Expression for user-specific tokens.

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?

Explore possible concept of data bags for HTTP messages / API Blueprint assets.

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.

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.

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:

• blueprint files would probably need to have a different extension, because parsers in 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)
• the output would have to fit within allowed HTML elements, so probably no rich styling could apply anyway :-(

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.

Create a brief glossary of terms accompanying the API Blueprint specification.

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.

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?

Direct support for hypermedia and modeling actions & relations.

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

Provide the ability to define HTTP headers that can be referenced later.

Note: This can also be covered as "Global HTTP Headers".

Revisit proposed URI and Body parameters syntax.

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.

1. Which of these is strictly legal, in a "won't break in the future" sort of way?
2. Where is this documented, or shouldn't it be?

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

Difference of the name throughout the document...

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?

Support for media types and content negotiation.

Add the possibility to use Markdown links wherever an asset is expected (e.g. a payload body or schema).

Reformat the API Blueprint specification document so it serves information on sections in more structured, unified and easier to ready way.

I'd love to have

+ Response (application/json)

        []

as a shortcut for

+ Response 200 (application/json)

        []

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)

Provide the ability to define arbitrary payloads that can be referenced later (similar to the concept of resource object).

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

Describe URI query parameters globally, share amongst several resources

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.

Introducing the API Blueprint Object Trait. Addressing following milestones:

• #11 Authentication
• #17 Referenced HTTP headers
• #19 Referenced Payloads
• #24 Global query URI parameter
• #36 Support for Scopes
• #38 Support for Specific Metadata

Full implementation of traits assume following issues are implemented:

• #25 Message-body Parameters Description
• #26 Parametric Headers Description
• #28 Nested Parameters

What is a Trait

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:

• API
• Resource Group
• Resource
• Resource Model
• Action
• Request
• Response
• Parameter

Traits can be used add additional semantics or a set of characteristics to an object.

Semantic Trait

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`

Characteristic Trait

In addition to its semantic meaning a trait can also express certain characteristic of object's payload(s).

Where payload characteristic is one of:

• parameter characteristic
• property characteristic (new in Format 1B)
• [request | response] header characteristic
• body characteristic
• schema characteristic

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

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.

To be discussed: Inheritance of headers / responses / resources.