Propose root transitions of an API

draft/root-transitions.md

@@ -0,0 +1,54 @@
+---
+RFC: XXXX
+Author: Kyle Fuller
+Status: Draft
+Created: 2015-09-21
+Last Modified: 2015-09-21
+---
+
+# API Blueprint RFC XXXX: Root Transitions
+
+## Table of Contents
+
+- [Abstract](#abstract)
+- [Motivation](#motivation)
+- [Proposed Syntax](#proposed-syntax)
+
+## Abstract
+
+This RFC proposes that you can define the transitions you may make from the
+root of an API described by API Blueprint.
+
+## Motivation
+
+There is currently no way to express transitions from the root of an API.
+You can express transitions from a resource using the relation keyword, but it
+is not currently possible to express transitions from the root of the API to
+other resources.
+
+## Proposed Syntax
+
+I propose adding a new section to API Blueprint called "Root Transitions"
+which allows you to list all of the transitions available from the root of an
+API using MSON syntax to reference the other resources.
+
+### Example
+
+Below, you can see an example of the proposed syntax, where we have a
+transition with the relation identifier `questions` to the "Questions
+Collection" resource.
+
+```apib
+## Root Transitions
+
++ questions (Questions Collection) - A transition to view the available questions.
+
+## Questions Collection [/questions]
+### View [GET]
+
++ Response 200 (application/json)
+    + Attributes (array[Question])
+
+### Question [/questions/{id}]
+```
+