Merge pull request #64 from apiaryio/1A

1A revision 3: Deprecate resource & action level headers

API Blueprint Specification.md

@@ -1,11 +1,11 @@
 ---
 Author: z@apiary.io
-Version: 1A2
+Version: 1A3
 
 ---
 
 # API Blueprint Language Specification
-### Format 1A revison 2
+### Format 1A revision 3
 
 ## Contents
 1. [Introduction](#Introduction)
@@ -23,11 +23,11 @@ Version: 1A2
     3. [Resource Group Section](#ResourceGroups)    
         1. [Resource Section](#ResourceSection)
             1. [Resource Parameters Section](#ResourceParametersSection)
-            2. [Resource Headers Section](#ResourceHeadersSection)
+            2. [Resource Headers Section](#ResourceHeadersSection) (deprecated)
             3. [Resource Model Section](#ResourceModelSection)
             4. [Resource Action Section](#ResourceActionSection)
                 1. [Action Parameters Section](#ActionParametersSection)
-                2. [Action Headers Section](#ActionHeadersSection)
+                2. [Action Headers Section](#ActionHeadersSection) (deprecated)
                 3. [Action Request Section](#ActionRequestSection)
                 4. [Action Response Section](#ActionResponseSection)
 5. [Payload Structure](#Payload)
@@ -302,7 +302,7 @@ If no **HTTP Request Method** is specified, this section **should include** at l
 In addition to any mandatory nested sections this section **may include** the following additional subsections:
 
 * [Parameters Section](#ResourceParametersSection)
-* [Headers Section](#ResourceHeadersSection)
+* [Headers Section](#ResourceHeadersSection) (deprecated)
 * [Model Section](#ResourceModelSection)
 * [Action Section](#ResourceActionSection),  if **no** HTTP Request Method is specified
 
@@ -390,6 +390,8 @@ Example:
 
 <a name="ResourceHeadersSection"></a>
 #### 4.3.1.2 Resource Headers Section
+**Deprecated:** This section is deprecated as of 1A3 and will be removed in a future revision of API Blueprint. Use respective request / response [headers section](#PayloadHeadersSection) instead.
+
 **Optional**. Specifies the message-headers of every transaction on this resource.
 
 Refer to [Payload Headers Subsection](#PayloadHeadersSection) for this section's syntax definition.
@@ -439,7 +441,7 @@ This section **should include** at least one [Response Subsection](#ActionRespon
 * [Parameters Section](#ResourceParametersSection)
 * [Request Section](#ActionRequestSection)
 * [Response Section](#ActionResponseSection)
-* [Headers Section](#ResourceHeadersSection)
+* [Headers Section](#AactionHeadersSection) (deprecated)
 
 One [Resource Section](#ResourceSection) can contain **one or more different** Action Sections.
 
@@ -467,6 +469,8 @@ Refer to [Resource Parameters Section](#ResourceParametersSection) for this sect
 
 <a name="ActionHeadersSection"></a>
 #### 4.3.1.4.2. Action Headers Section
+**Deprecated:** This section is deprecated as of 1A3 and will be removed in a future revision of API Blueprint. Use respective request / response [headers section](#PayloadHeadersSection) instead.    
+
 **Optional**. Specifies the message-headers of every transaction within this action's context.
 
 Refer to [Payload Headers Subsection](#PayloadHeadersSection) for this section's syntax definition.

examples/7. Parameters.md

@@ -8,7 +8,7 @@ But first let's add more messages to our system. For that we would need introduc
 ## API Blueprint
 + [Previous: Requests](6.%20Requests.md)
 + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/7.%20Parameters.md)
-+ [Next: Headers](8.%20Headers.md)
++ [Next: Resource Model](8.%20Resource%20Model.md)
 
 # Group Messages
 Group of all messages-related resources.

examples/9. Resource Model.md → examples/8. Resource Model.md

@@ -6,8 +6,8 @@ Resource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-
 Furthermore, in API Blueprint, any `resource model` you have defined can be referenced later saving you lots of time maintaining your API blueprint. You simply define a resource model as any payload (e. g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/6.%20Requests.md) or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) and then reference it later where you would normally write a `request` or `response`.
 
 ## API Blueprint
-+ [Previous: Headers](8.%20Headers.md)
-+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/9.%20Resource%20Model.md)
++ [Previous: Parameters](7.%20Parameters.md)
++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/8.%20Resource%20Model.md)
 
 # Group Messages
 Group of all messages-related resources.