Abstract protocol layer

[zdne]

Separate protocol layer from the description of the API semantics. The idea is to move protocol specifics from existing Resource and Action sections into new sections.

This breaks the API Design into two parts:

1. domain semantics (= what)
2. protocol specific details (= how)

Currently the two are mixed. This hinders the purpose of the API and leads to tight coupling with the client. Making the API harder to design, maintain and evolve.

This should follow the Resource Blueprint concept in introducing keywords for resource and action sections – Resource and Action keyword – which enables definition of Resources and Actions without URLs and HTTP methods. Protocol specifics should be mixed in later in a (new) protocols section.

# My API
# Resource Blog Post
- attributes

## Action Retrieve a Post
- relation: self
- parameters
- attributes
...

## HTTP
...

See the Resource Blueprint concept for details.

Related issues #288 and #13

[toobulkeh]

would this be related to a top-level section control? Currently there are the "Introduction" and "Reference" sections. It would be useful to customize those.

For example I'd like to break apart our reference section into several domain "what" sections.

1. Introduction
2. Support Reference
   • Tickets
   • Knowledge Base
3. Billing Reference
   • Agreements
   • Invoices
4. Profile Reference
   • Accounts
   • Users

There will definitely be some cross-polination, but this would be easier to digest than the current:

1. Introduction
2. Reference
   • Accounts
   • Agreements
   • Tickets
   • Users

I realize grouping probably exists for this method, but we use grouping for the further layer:

1. Group Users
   • All users (endpoint)
   • One user (endpoint)
   • Current user (endpoint)
   • Account's users (endpoint)

[zdne]

would this be related to a top-level section control? Currently there are the "Introduction" and "Reference"

Not really this issue is about conceptually separating the abstraction levels in API Blueprint, in this case, resource and action semantics description from the protocol details.

See http://blog.apiary.io/2015/12/17/API-Blueprint-Future

I believe what are you asking is how the documentation gets rendered in a documentation rendering tool (like Apiary or Aglio) but that is not in the scope of this issues.