Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Abstract protocol layer #289
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:
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 –
# My API # Resource Blog Post - attributes ## Action Retrieve a Post - relation: self - parameters - attributes ... ## HTTP ...
See the Resource Blueprint concept for details.
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.
There will definitely be some cross-polination, but this would be easier to digest than the current:
I realize grouping probably exists for this method, but we use grouping for the further layer:
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.
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.