├── README.md ├── rfcs ├── 0001-rfc-process.md ├── 0002-authentication.md ├── 0003-authentication-basic.md ├── 0004-request-parameters.md └── 0005-authentication-oauth2.md └── template.md /README.md: -------------------------------------------------------------------------------- 1 | # API Blueprint Request for Comments 2 | 3 | Many changes, including bug fixes and documentation improvements can be 4 | implemented and reviewed via the normal GitHub pull request workflow. 5 | 6 | Some changes though are "substantial", and we ask that these be put through a 7 | bit of a design process and produce a consensus among the API Blueprint team. 8 | 9 | The "RFC" (request for comments) process is intended to provide a consistent 10 | and controlled path for new features to enter the language. 11 | 12 | ## When you need to follow this process 13 | 14 | You need to follow this process if you intend to make "substantial" changes to 15 | the API Blueprint language or specification. 16 | 17 | ## What the process is 18 | 19 | In short, to get a major feature added to the API Blueprint language and/or 20 | parser, one must first get an RFC relevant to that feature merged and accepted 21 | into the RFC repository as a markdown file. At that point the RFC is 'active' 22 | and may be implemented with the goal of eventual inclusion into API Blueprint. 23 | 24 | Please see [RFC 1](rfcs/0001-rfc-process.md) for more details. 25 | 26 | ## Related 27 | 28 | The RFC process is inspired by, and very similar to 29 | [PEP](https://www.python.org/dev/peps/), [DEP](https://github.com/django/deps) 30 | and the [Rust RFCs](https://github.com/rust-lang/rfcs). 31 | 32 | -------------------------------------------------------------------------------- /rfcs/0001-rfc-process.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 1 3 | Author: Kyle Fuller 4 | Status: Final 5 | Created: 2015-09-21 6 | Last Modified: 2016-01-26 7 | --- 8 | 9 | # API Blueprint RFC 1: RFC Template 10 | 11 | ## Table of Contents 12 | 13 | - [What is an RFC](#what-is-an-rfc) 14 | - [RFC Submission Workflow](#rfc-submission-workflow) 15 | - [Pre-proposal](#pre-proposal) 16 | - [Submitting draft RFC](#submitting-draft-rfc) 17 | - [Discussion, development, and updates](#discussion-development-and-updates) 18 | - [Review & Resolution](#review--resolution) 19 | - [Implementation](#implementation) 20 | 21 | ## What is an RFC? 22 | 23 | RFC (or Request for Comment) are design documents providing information for new 24 | features within the API Blueprint language. RFCs provide concise technical 25 | specifications of features along with rationales. 26 | 27 | RFCs are intended to be the primary mechanism for proposing new features to the 28 | API Blueprint language allowing community input on any issues, and for 29 | documenting design decisions that have gone into the API Blueprint language. 30 | 31 | ## RFC Submission Workflow 32 | 33 | The RFC process looks something like this: 34 | 35 | 1. [Pre-proposal](#pre-proposal) 36 | 2. [Submitting draft RFC](#submitting-draft-rfc) for a change you would like 37 | to make to the API Blueprint language. 38 | 3. [Discussion, development, and updates](#discussion-development-and-updates) - 39 | The RFC will be discussed, improved, and updated as feedback comes in. 40 | 4. [Review & Resolution](#review--resolution) - The RFC is concidered by the API 41 | Blueprint team and is either accepted or rejected. 42 | 5. [Implementation](#implementation) - The implementation of the proposed RFC 43 | is completed. 44 | 45 | ### Pre-proposal 46 | 47 | The RFC process begins with a new idea or change for API Blueprint. It is 48 | recomended that you reach out to the API Blueprint community to determine if 49 | the proposal would make sense, and to save the author time if the proposal 50 | would be outright rejected for any reason. 51 | 52 | Asking the API Blueprint community first if an idea is original help 53 | prevent too much time being spent on something that is guaranteed to be 54 | rejected based on prior discussions (searching the Internet does not always 55 | do the trick). 56 | 57 | It also helps to make sure the idea is applicable to the entire community and 58 | not just the author 59 | 60 | ### Submitting draft RFC 61 | 62 | A draft RFC should be presented in the form of a pull request to the API 63 | Blueprint RFC repository. 64 | 65 | 1. Fork the API Blueprint RFC repository 66 | 2. Copy `template.md` to the `rfcs` directory and rename it to to reflect the 67 | title of the RFC. For example, if the RFC was to propose the ability to 68 | define headers using MSON, then the title may be "MSON Headers" and the 69 | filename would become `mson-headers.md`. 70 | 3. Fill out the template RFC. 71 | - Number - Please leave the RFC number blank at this moment, once accepted, 72 | the RFC will be assigned a number. 73 | - Motivation - The most critical part of an RFC is to explain why this RFC is 74 | needed and why existing solutions are indadequate to address the problem that 75 | the RFC solves. RFC submissions without sufficient motiviation may be 76 | rejected. 77 | - Rationale - The rationale fleshes out the specification by describing 78 | what motivated the design and why particiular design decisions were made. 79 | It should describe alternate designs that were considered and related 80 | work. 81 | 82 | The rationale should provide evidence of consensus within the community 83 | and discuss important objections or concerns raised during discussion. 84 | - Backwards Compatibility - All RFCs that introduce backwards 85 | incompatibilities MUST include a section describing these 86 | incompatibilities and their severity. 87 | 88 | ### Discussion, development, and updates 89 | 90 | At this point there will generally be more discussion, and of course updates 91 | to the RFC. 92 | 93 | Updates to a RFC can be submitted as pull requests; once again, a core 94 | developer will merge those pull requests (typically they don't require much if 95 | any review). In cases where the Author has commit access (fairly common), the 96 | Author should just update the draft RFC directly. 97 | 98 | ### Review & Resolution 99 | 100 | Once the author has completed the RFC, the API Blueprint team will review and 101 | finally change the RFCs status to accepted. 102 | 103 | For a RFC to be accepted it must meet certain minimum criteria. It must be a 104 | clear and complete description of the proposed change. 105 | 106 | ### Implementation 107 | 108 | Finally, once an RFC has been accepted, the implementation must be completed. 109 | When the implementation is complete and incorporated into the API Blueprint 110 | specification and any related parsers. The status will be changed to "Final". 111 | -------------------------------------------------------------------------------- /rfcs/0002-authentication.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 2 3 | Author: Kyle Fuller 4 | Status: Draft 5 | Created: 2015-09-22 6 | Last Modified: 2015-10-22 7 | --- 8 | 9 | # API Blueprint RFC 2: Authentication Framework 10 | 11 | ## Table of Contents 12 | 13 | - [Abstract](#abstract) 14 | - [Motivation](#motivation) 15 | - [Rationale](#rationale) 16 | - [Backwards Compatibility](#backwards-compatibility) 17 | 18 | ## Abstract 19 | 20 | This RFC proposes an authentication framework that you can use to mark 21 | resource groups, resources, actions or requests as authenticated. 22 | Along with defining a framework for creating authentication schemes. 23 | 24 | This RFC does not propose any specific authentication schemes, those are to be 25 | created outside of this RFC. 26 | 27 | ## Motivation 28 | 29 | Being able to express authentication in a machine readable way will allow tools 30 | around API Blueprint to utilise authentication. 31 | 32 | ## Rationale 33 | 34 | ### Authentication Scheme Type Definition 35 | 36 | Authentication schemes can be defined in an API Blueprint under an 37 | "Authentication Schemes" heading in an API Blueprint. Inside this header 38 | may be a sub-heading which specifies any named authentication types 39 | supported which may be supported by the API. 40 | 41 | Users may extend other authentication types to define new authentication 42 | schemes. 43 | 44 | For example, to define a named authentication scheme called "Passphrase" which 45 | inherits from another authentication scheme "Basic", we can write the 46 | following in an API Blueprint: 47 | 48 | ```apib 49 | ## Authentication Schemes 50 | 51 | ### Passphrase (Basic) 52 | ``` 53 | 54 | **NOTE**: *The basic scheme is used as an example in this RFC, and is not 55 | defined within this RFC.* 56 | 57 | Under the authentication scheme heading, you may describe authentication 58 | schemes as MSON Type Sections. You may attach a description and define 59 | properties as list items. 60 | 61 | An authentication scheme may provide a set of properties with default values. 62 | 63 | ```apib 64 | ### Passphrase (Basic) 65 | 66 | Polls API supports the Basic authentication scheme used with 67 | pre-existing user accounts. 68 | ``` 69 | 70 | Inside an authentication scheme, you can define responses that may be given 71 | when an authentication scheme is used. For example to indicate the response 72 | that is given when the authentication or permission of the user using 73 | authentication is incorrect. 74 | 75 | ```apib 76 | ### Passphrase (Basic) 77 | 78 | + Response 403 (application/json) 79 | + Attributes 80 | + error: `The user does not have access.` 81 | ``` 82 | 83 | ## Authenticated Keyword 84 | 85 | The `Authenticated` keyword can be used to mark a resource group, resource, or 86 | request example to use authentication. 87 | 88 | When the authenticated keyword is used on it's own, it will indicate that all 89 | named authentication schemes defined in the `Authentication Schemes` section 90 | are supported. 91 | 92 | For example: 93 | 94 | ```apib 95 | + Authenticated 96 | ``` 97 | 98 | You may explictly mention a named or base authentication scheme to specify that 99 | only that scheme is supported. 100 | 101 | ```apib 102 | + Authenticated (Basic) 103 | ``` 104 | 105 | You may overide any properties defined in a base or named scheme. 106 | 107 | ```apib 108 | + Authenticated (Passphrase) 109 | + username: katie 110 | ``` 111 | 112 | You may also provide failure responses in anonymous authentication schemes. 113 | 114 | ```apib 115 | + Authenticated (Basic) 116 | + Response 403 (application/json) 117 | + Attributes 118 | + error: `The user does not have access.` 119 | ``` 120 | 121 | You specify that multiple authentication schemes are supported, using an 122 | `enum`. 123 | 124 | ```apib 125 | + Authenticated (enum) 126 | + (Basic) 127 | + username: kyle 128 | + password: b2952d03bda09cb5f63b0162fbbee77c 129 | + (Passphrase) 130 | ``` 131 | 132 | If you do not need to override properties, then you may use the shorthand equivalence: 133 | 134 | ```apib 135 | + Authenticated (enum[Basic, Passphrase]) 136 | ``` 137 | 138 | ### Resource Groups 139 | 140 | The authenticated keyword may be used within a resource group to indicate that 141 | all child resources, actions and requests inside the resource group support 142 | the specified authentication schemes. Any specific resource, action, or 143 | request may override the inherited authentication schemes. 144 | 145 | Resource groups may be marked as authenticated using the following: 146 | 147 | ```apib 148 | ## Group Questions 149 | 150 | + Authenticated 151 | ``` 152 | 153 | ```apib 154 | ## Group Questions 155 | 156 | + Authenticated (Basic) 157 | + username: kyle 158 | + password: b2952d03bda09cb5f63b0162fbbee77c 159 | ``` 160 | 161 | ```apib 162 | + Authenticated (enum) 163 | + (Basic) 164 | + username: kyle 165 | + password: b2952d03bda09cb5f63b0162fbbee77c 166 | + (Named) 167 | ``` 168 | 169 | ### Resources 170 | 171 | Resources, including all the actions and requests within the resource may be 172 | marked as authenticated using the `Authenticated` keyword as follows: 173 | 174 | ```apib 175 | ## Questions Collection [/questions] 176 | 177 | + Authenticated 178 | ``` 179 | 180 | ```apib 181 | ## Questions Collection [/questions] 182 | 183 | + Authenticated (Basic) 184 | + username: kyle 185 | + password: b2952d03bda09cb5f63b0162fbbee77c 186 | ``` 187 | 188 | ### Actions 189 | 190 | Actions, including all example requests within the action may be marked as 191 | authenticated using the `Authenticated` keyword as follows: 192 | 193 | ```apib 194 | ### View list of questions [GET] 195 | 196 | + Authenticated 197 | ``` 198 | 199 | ```apib 200 | ### View list of questions [GET] 201 | 202 | + Authenticated (Basic) 203 | + username: kyle 204 | + password: b2952d03bda09cb5f63b0162fbbee77c 205 | ``` 206 | 207 | ### Request Examples 208 | 209 | Request examples can be marked as authenticated by specifing an authenticated 210 | keyword inside the request as a sub-item. 211 | 212 | ```apib 213 | + Request 214 | + Authenticated 215 | ``` 216 | 217 | ```apib 218 | + Request 219 | + Authenticated (Basic) 220 | + username: kyle 221 | + password: b2952d03bda09cb5f63b0162fbbee77c 222 | ``` 223 | 224 | **NOTE**: *You may not define example responses that an authentication scheme 225 | may return within an anonymous authentication scheme inside a request example. 226 | This limitation is to avoid defining responses within a request to prevent 227 | complexity.* 228 | -------------------------------------------------------------------------------- /rfcs/0003-authentication-basic.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 3 3 | Author: Kyle Fuller 4 | Status: Draft 5 | Created: 2015-09-22 6 | Last Modified: 2015-09-28 7 | --- 8 | 9 | # API Blueprint RFC 3: Basic Authentication Scheme 10 | 11 | ## Table of Contents 12 | 13 | - [Abstract](#abstract) 14 | - [Motivation](#motivation) 15 | - [Rationale](#rationale) 16 | - [Backwards Compatibility](#backwards-compatibility) 17 | 18 | ## Abstract 19 | 20 | This RFC adds the "Basic" authentication scheme for the Authentication 21 | framework proposed in RFC 2. 22 | 23 | ## Motivation 24 | 25 | Basic authentication is a commonly used authentication mechanism, and is part 26 | of the HTTP/1.1 specification defined in 27 | [RFC1945 section 11.1](http://tools.ietf.org/html/rfc1945#section-11.1). 28 | 29 | ## Rationale 30 | 31 | The "Basic" authentication scheme is based on the model that the user 32 | agent must authenticate itself with a user-ID and a password. 33 | 34 | As such, a basic authentication scheme may configure two properties, 35 | `username` and `password`. These properties indicate a sample username and 36 | password that may be used. 37 | 38 | For example, as a named authentication scheme: 39 | 40 | ```apib 41 | ### Auth (Basic) 42 | 43 | + username: kyle 44 | + password: b2952d03bda09cb5f63b0162fbbee77c 45 | ``` 46 | 47 | As an anonymous scheme: 48 | 49 | ```apib 50 | + Authenticated (Basic) 51 | + username: kyle 52 | + password: b2952d03bda09cb5f63b0162fbbee77c 53 | ``` 54 | 55 | There are no default values for the sample `username` and `password`. When 56 | these are both unset, there is no sample credentials. 57 | 58 | Implementations of the Basic Authentication Scheme may provide sufficient 59 | warnings or errors if a `username` or `password` is configured without 60 | the counterpart. 61 | -------------------------------------------------------------------------------- /rfcs/0004-request-parameters.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 0004 3 | Author: Kyle Fuller 4 | Status: Accepted 5 | Created: 2015-11-20 6 | Last Modified: 2015-11-30 7 | --- 8 | 9 | # API Blueprint RFC 0004: Request Parameters 10 | 11 | ## Table of Contents 12 | 13 | - [Abstract](#abstract) 14 | - [Motivation](#motivation) 15 | - [Rationale](#rationale) 16 | - [Backwards Compatibility](#backwards-compatibility) 17 | 18 | ## Abstract 19 | 20 | These changes propose a way to attach different URI Parameter values 21 | to different transaction examples, allowing you to provide alternative 22 | responses based on matched URI Parameters. 23 | 24 | ## Motivation 25 | 26 | These changes will allow users to express how responses may be different when a 27 | requesting client sends different URI parameter values. 28 | 29 | Requests with different parameters will also allow tooling around API Blueprint 30 | such as testing tools and mocking tools to provide better matching of responses 31 | based on different request parameters. 32 | 33 | ## Rationale 34 | 35 | This proposal will add the ability to attach parameters to a request. The 36 | parameters attached to a request with override and not inherit from the 37 | previous parameter definition. 38 | 39 | ```apib 40 | ### Search for a question [GET /questions{?query,limit}] 41 | 42 | + Parameters 43 | + query: language - Search query 44 | + limit: 20 (number, optional) - Maximum number of questions returned 45 | 46 | + Response 200 (application/json) 47 | 48 | [ 49 | { "question": "Favourite programming language?" }, 50 | { "question": "API Description language preference" } 51 | ] 52 | 53 | + Request A search limited to one result 54 | + Parameters 55 | + query: language 56 | + limit: 1 57 | 58 | + Response 200 (application/json) 59 | 60 | [ 61 | { "question": "Favourite programming language?" } 62 | ] 63 | ``` 64 | -------------------------------------------------------------------------------- /rfcs/0005-authentication-oauth2.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: 5 3 | Author: Kyle Fuller 4 | Status: Draft 5 | Created: 2015-09-28 6 | Last Modified: 2015-09-29 7 | --- 8 | 9 | # API Blueprint RFC 5: OAuth 2 Authentication Scheme 10 | 11 | ## Table of Contents 12 | 13 | - [Abstract](#abstract) 14 | - [Motivation](#motivation) 15 | - [Rationale](#rationale) 16 | - [Backwards Compatibility](#backwards-compatibility) 17 | 18 | ## Abstract 19 | 20 | This RFC adds the "OAuth 2" authentication scheme for the Authentication 21 | framework proposed in RFC 2. OAuth 2 is defined in 22 | [RFC 6749](http://tools.ietf.org/html/rfc6749). 23 | 24 | ## Motivation 25 | 26 | OAuth 2 is a highly common authentication mechanism and it's oftenly used in APIs. 27 | 28 | ## Rationale 29 | 30 | You can use the OAuth 2 Authentication scheme by defining it within the 31 | "Authentication Schemes" section of an API Blueprint. 32 | 33 | ```apib 34 | ### Auth (OAuth 2) 35 | ``` 36 | 37 | ### Scopes 38 | 39 | Supported scopes may be listed inside the authentication schemes 40 | 41 | ```apib 42 | ### Auth (OAuth 2) 43 | 44 | + scopes 45 | + user - A user scope, allowing you access to read the user information 46 | + user.email - A user scope, allowing you access to read the user's email addresses 47 | ``` 48 | 49 | ### Endpoints 50 | 51 | #### Authorization endpoint 52 | 53 | You may describe an authorization endpoint inside the authentication scheme 54 | using the `authorize` relation identifier. 55 | 56 | This endpoint represents the the authorization endpoint described in 57 | [RFC6749 section 3.1](http://tools.ietf.org/html/rfc6749#section-3.1). 58 | 59 | Inside the authorization endpoint you can describe the parameters that this 60 | endpoint takes along with the parameters it will return during the 61 | `Redirect Callback`. 62 | 63 | The `Redirect` keyword has been added to represent the request that will be 64 | made to the `Redirect Callback`. 65 | 66 | ```apib 67 | #### Authorization [GET /authorize] 68 | 69 | + Relation: authorize 70 | + Request 71 | + Parameters 72 | + `response_type`: code (Response Type, required) 73 | + `client_id`: b58051708627fa6a5b7e49108f3c7574 (Client ID, required) 74 | + state (State) 75 | + scope (Scope) 76 | + `redirect_uri` (Redirect Callback, required) 77 | 78 | + Redirect 79 | + Parameters 80 | + code (Code) 81 | + state (State) 82 | ``` 83 | 84 | You can describe multiple HTTP transactions within the authorization 85 | endpoint. For example to also describe a `token` `response_type` you 86 | may use the following: 87 | 88 | ```apib 89 | + Request 90 | + Parameters 91 | + `response_type`: token (Response Type, required) 92 | + `client_id`: b58051708627fa6a5b7e49108f3c7574 (Client ID, required) 93 | + `redirect_uri` (Redirect Callback, required) 94 | 95 | + Redirect 96 | + Parameters 97 | + `access_token` (Token) 98 | + `token_type`: Bearer (Token Type) 99 | ``` 100 | 101 | Tools that understand the OAuth 2 authentication scheme should understand the 102 | semantic meaning of the following parameter types within the authorization 103 | endpoint as described in the OAuth 2 specification. 104 | 105 | - Response Type 106 | - Client ID 107 | - Client Secret 108 | - State 109 | - Scope 110 | - Redirect Callback 111 | - Token 112 | - Token Type 113 | 114 | #### Token endpoint 115 | 116 | The token endpoint is used by the client to obtain an access token as 117 | described by [RFC 6749 section 3.2](http://tools.ietf.org/html/rfc6749#section-3.2). 118 | This endpoint is identified by the `token` relation identifier. 119 | 120 | API Blueprint tooling can use the types of parameters or attributes to 121 | understand the content being placed within them. Although a user may add 122 | any additonal types of fields as required by the API: 123 | 124 | - Grant 125 | - Code 126 | - Redirect Callback 127 | - Client ID 128 | - Client Secret 129 | - Token 130 | - Token Type 131 | - Refresh Token 132 | 133 | For example, to describe a token endpoint that uses the `POST` HTTP 134 | method against the `/token` URI you can use the following: 135 | 136 | ```apib 137 | ### Token [POST /token] 138 | 139 | + Relation: token 140 | + Request 141 | + Parameters 142 | + `grant_type`: `authorization_code` (Grant) 143 | + code (Code) 144 | + `redirect_uri` (Redirect Callback) 145 | + `client_id` (Client ID) 146 | + `client_secret` (Client Secret) 147 | 148 | + Response 200 (application/json) 149 | + Attributes 150 | + `access_token` (Token) 151 | ``` 152 | 153 | When a parameter is not described in the URI template for the URI, it is 154 | assumed to be a query parameter. 155 | 156 | ##### Defining custom request and responses that can return an access token. 157 | 158 | You can define any custom flow providing it returns a response including 159 | a access token attribute. 160 | 161 | ```apib 162 | ### Token [POST /token] 163 | 164 | + Relation: token 165 | + Request (application/json) 166 | + `grant_type`: password (Grant) 167 | + username 168 | + password 169 | 170 | + Response 200 (application/json) 171 | + Attributes 172 | + `access_token` (Token) 173 | ``` 174 | 175 | ```apib 176 | ### Token [POST /token] 177 | 178 | + Relation: token 179 | 180 | + Request (application/x-www-form-urlencoded) 181 | + Headers: 182 | + Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 183 | 184 | + Attributes 185 | + `grant_type`: `refresh_token` 186 | + `refresh_token` (Refresh Token) 187 | 188 | + Response 200 (application/json) 189 | + Attributes 190 | + `access_token` (Token) 191 | ``` 192 | 193 | #### Revocation Endpoint 194 | 195 | You may define an endpoint that can be used to revoke an access token using the 196 | `revoke` relation identifier. 197 | 198 | ```apib 199 | ### Revoke an access token [DELETE /revoke] 200 | 201 | + Relation: revoke 202 | + Response 204 203 | ``` 204 | ### Access Token Types 205 | 206 | API Blueprint tooling may only support the Bearer token type as per described 207 | in this RFC, however any tooling may support other token types defined in 208 | the OAuth specification. 209 | 210 | #### Bearer Token 211 | 212 | As defined in [RFC6750](http://tools.ietf.org/html/rfc6750), the Bearer token 213 | may be used in many ways. 214 | 215 | Inside an OAuth 2 authentication scheme, you can show requests using a Bearer 216 | token under the `Bearer` heading. 217 | 218 | ```apib 219 | ### Bearer 220 | 221 | + Request 222 | + Headers 223 | + Authorization (Token) 224 | 225 | + Request (application/x-www-form-urlencoded) 226 | + `access_token` (Token) 227 | 228 | + Request (application/json) 229 | + `access_token` (Token) 230 | 231 | + Request 232 | + Parameters 233 | + `access_token` (Token) 234 | ``` 235 | 236 | ### Referencing an OAuth 2 authentication scheme 237 | 238 | When referencing an OAuth 2 scheme from a resource group, resource, action or 239 | example you may specify a comma separated list of OAuth 2 scopes that can be 240 | used. 241 | 242 | For example: 243 | 244 | ```apib 245 | + Request 246 | + Authenticated (Auth[user]) 247 | + Response 200 (application/json) 248 | + Attributes (User) 249 | 250 | + Request 251 | + Authenticated (Auth[user.email]) 252 | + Response 200 (application/json) 253 | + Attributes (User) 254 | + emails (array[Email]) 255 | ``` 256 | 257 | -------------------------------------------------------------------------------- /template.md: -------------------------------------------------------------------------------- 1 | --- 2 | RFC: XXXX 3 | Author: Kyle Fuller 4 | Status: Draft 5 | Created: 2015-09-21 6 | Last Modified: 2015-09-21 7 | --- 8 | 9 | # API Blueprint RFC XXXX: RFC Template 10 | 11 | ## Table of Contents 12 | 13 | - [Abstract](#abstract) 14 | - [Motivation](#motivation) 15 | - [Rationale](#rationale) 16 | - [Backwards Compatibility](#backwards-compatibility) 17 | 18 | Once you've made a copy of this template, remove this abstract, fill out the 19 | metadata above and the sections below, then submit the RFC. Follow the 20 | guidelines in RFC 1. 21 | 22 | ## Abstract 23 | 24 | This should be a short (~200 word) description of the technical issue being 25 | addressed. 26 | 27 | This (and the above metadata) is the only section strictly required to submit a 28 | draft RFC; the following sections can be barebones and fleshed out as you work 29 | through the RFC process. 30 | 31 | ## Motivation 32 | 33 | This section should explain why this RFC is needed. The motivation is critical 34 | for RFCs that want to add substantial new features or materially refactor 35 | existing ones. It should clearly explain why the existing solutions are 36 | inadequate to address the problem that the RFC solves. RFC submissions without 37 | sufficient motivation may be rejected outright. 38 | 39 | ## Rationale 40 | 41 | This section should flesh out out the specification by describing what 42 | motivated the specific design design and why particular design decisions were 43 | made. It should describe alternate designs that were considered and related 44 | work. 45 | 46 | The rationale should provide evidence of consensus within the community and 47 | discuss important objections or concerns raised during discussion. 48 | 49 | ## Backwards Compatibility 50 | 51 | If this RFC introduces backwards incompatibilities, you must must include this 52 | section. It should describe these incompatibilities and their severity, and 53 | what mitigation you plan to take to deal with these incompatibilities. 54 | 55 | --------------------------------------------------------------------------------