search

apiaryio / api-elements

API Elements is a structure for describing APIs and the complex data structures used within them.
http://apielements.org/
MIT License
28 stars 10 forks source link

Initial restructure for API Elements specification #1

Closed smizell closed 8 years ago

smizell commented 8 years ago

This removes everything about Refract and combines all namespaces into a single document.

danielgtaylor commented 8 years ago

Amazing light after-dinner reading you have here; I love it!

One high-level comment: it would be great if we can use syntax highlighting for all the MSON (e.g. element descriptions). Looks like I can't just use mson as the language on GitHub, so maybe it's time to add support for it?

smizell commented 8 years ago

I have added a few things for us to address later:

  1. When it is set, do you merge the values with those in the parent transition/resource or do the httpRequest hrefVariables completely override them? I think we should be explicit here.
  2. MSON is introduced here with no explanation. Should we put a note about it or something?
  3. https://github.com/apiaryio/api-elements/pull/1#discussion_r54202396
  4. https://github.com/apiaryio/api-elements/pull/1#discussion_r54202406
  5. https://github.com/apiaryio/api-elements/pull/1#discussion_r54202418
  6. https://github.com/apiaryio/api-elements/pull/1#discussion-diff-54202377
  7. https://github.com/apiaryio/api-elements/pull/1#discussion_r54202354
danielgtaylor commented 8 years ago

The plan is to merge this PR, then fix the above comments in subsequent PRs that will be smaller and easier to review until eventually we have these documents ready for consumption. See #2.