New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Abstract protocol layer #289

Open
zdne opened this Issue Dec 10, 2015 · 2 comments

Comments

Projects
None yet
2 participants
@zdne
Copy link
Contributor

zdne commented Dec 10, 2015

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

This comment has been minimized.

Copy link

toobulkeh commented Dec 22, 2015

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

This comment has been minimized.

Copy link
Contributor

zdne commented Dec 22, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment