├── .gitignore ├── assets ├── map.png ├── lifecycle.png └── logo_apiblueprint.png ├── examples ├── README.md ├── 3. Named Resource and Actions.md ├── 1. Simplest API.md ├── 4. Grouping Resources.md ├── 5. Responses.md ├── 2. Resource and Actions.md ├── 6. Requests.md ├── 8. Resource Model.md ├── 7. Parameters.md ├── Real World API.md ├── Gist Fox API.md └── Gist Fox API + Auth.md ├── LICENSE ├── README.md ├── Glossary of Terms.md ├── Tutorial.md └── API Blueprint Specification.md /.gitignore: -------------------------------------------------------------------------------- 1 | _site 2 | node_modules 3 | .DS_Store 4 | npm-debug.log -------------------------------------------------------------------------------- /assets/map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tkh44/api-blueprint/master/assets/map.png -------------------------------------------------------------------------------- /assets/lifecycle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tkh44/api-blueprint/master/assets/lifecycle.png -------------------------------------------------------------------------------- /assets/logo_apiblueprint.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/tkh44/api-blueprint/master/assets/logo_apiblueprint.png -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # API Blueprint Examples 2 | All files in this directory are actual **valid API blueprints**. Since they are saved with the `.md` extension GitHub automatically renders them during viewing. 3 | 4 | **To view an API blueprint source make sure to view the file as "raw".** 5 | -------------------------------------------------------------------------------- /examples/3. Named Resource and Actions.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Named Resource and Actions API 4 | This API example demonstrates how to name a resource and its actions, to give the reader a better idea about what the resource is used for. 5 | 6 | ## API Blueprint 7 | + [Previous: Resource and Actions](2.%20Resource%20and%20Actions.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/3.%20Named%20Resource%20and%20Actions.md) 9 | + [Next: Grouping Resources](4.%20Grouping%20Resources.md) 10 | 11 | # My Message [/message] 12 | OK, `My Message` probably isn't the best name for our resource but it will do for now. Note the URI `/message` is enclosed in square brackets. 13 | 14 | ## Retrieve a Message [GET] 15 | Now this is informative! No extra explanation needed here. This action clearly retrieves the message. 16 | 17 | + Response 200 (text/plain) 18 | 19 | Hello World! 20 | 21 | ## Update a Message [PUT] 22 | `Update a message` - nice and simple naming is the best way to go. 23 | 24 | + Request (text/plain) 25 | 26 | All your base are belong to us. 27 | 28 | + Response 204 29 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | (The MIT License) 2 | 3 | Copyright (c) 2014 Apiary Inc. . 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining 6 | a copy of this software and associated documentation files (the 7 | 'Software'), to deal in the Software without restriction, including 8 | without limitation the rights to use, copy, modify, merge, publish, 9 | distribute, sublicense, and/or sell copies of the Software, and to 10 | permit persons to whom the Software is furnished to do so, subject to 11 | the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be 14 | included in all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 20 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 21 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 22 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /examples/1. Simplest API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # The Simplest API 4 | This is one of the simplest APIs written in the **API Blueprint**. 5 | One plain resource combined with a method and that's it! We will explain what is going on in the next installment - [Resource and Actions](2.%20Resource%20and%20Actions.md). 6 | 7 | **Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/1.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser. 8 | 9 | Also please keep in mind that every single example in this course is a **real API Blueprint** and as such you can **parse** it with the [API Blueprint parser](https://github.com/apiaryio/snowcrash) or one of its [bindings](https://github.com/apiaryio/snowcrash#bindings). 10 | 11 | ## API Blueprint 12 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/1.%20Simplest%20API.md) 13 | + [Next: Resource and Actions](2.%20Resource%20and%20Actions.md) 14 | 15 | # GET /message 16 | + Response 200 (text/plain) 17 | 18 | Hello World! 19 | -------------------------------------------------------------------------------- /examples/4. Grouping Resources.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Grouping Resources API 4 | This API example demonstrates how to group resources and form **groups of resources**. You can create as many or as few groups as you like. If you do not create any group all your resources will be part of an "unnamed" group. 5 | 6 | ## API Blueprint 7 | + [Previous: Named Resource and Actions](3.%20Named%20Resource%20and%20Actions.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/4.%20Grouping%20Resources.md) 9 | + [Next: Responses](5.%20Responses.md) 10 | 11 | # Group Messages 12 | Group of all messages-related resources. 13 | 14 | This is the first group of resources in this document. It is **recognized** by the **keyword `group`** and its name is `Messages`. 15 | 16 | Any following resource definition is considered to be a part of this group until another group is defined. It is **customary** to increase header level of resources (and actions) nested under a resource. 17 | 18 | ## My Message [/message] 19 | 20 | ### Retrieve a Message [GET] 21 | 22 | + Response 200 (text/plain) 23 | 24 | Hello World! 25 | 26 | ### Update a Message [PUT] 27 | 28 | + Request (text/plain) 29 | 30 | All your base are belong to us. 31 | 32 | + Response 204 33 | 34 | # Group Users 35 | Group of all user-related resources. 36 | 37 | This is the second group in this blueprint. For now, no resources were defined here and as such we will omit it from the next installement of this course. 38 | -------------------------------------------------------------------------------- /examples/5. Responses.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Responses API 4 | In this API example we will discuss what information a response can bear and how to define multiple responses. Technically a response is represented by a payload that is sent back in response to a request. 5 | 6 | ## API Blueprint 7 | + [Previous: Grouping Resources](4.%20Grouping%20Resources.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/5.%20Responses.md) 9 | + [Next: Requests](6.%20Requests.md) 10 | 11 | # Group Messages 12 | Group of all messages-related resources. 13 | 14 | ## My Message [/message] 15 | 16 | ### Retrieve a Message [GET] 17 | This action has **two** responses defined: One returing a plain text and the other a JSON representation of our resource. Both has the same HTTP status code. Also both responses bear additional information in the form of a custom HTTP header. Note that both responses have set the `Content-Type` HTTP header just by specifying `(text/plain)` or `(application/json)` in their respective signatures. 18 | 19 | + Response 200 (text/plain) 20 | 21 | + Headers 22 | 23 | X-My-Message-Header: 42 24 | 25 | + Body 26 | 27 | Hello World! 28 | 29 | + Response 200 (application/json) 30 | 31 | + Headers 32 | 33 | X-My-Message-Header: 42 34 | 35 | + Body 36 | 37 | { "message": "Hello World!" } 38 | 39 | ### Update a Message [PUT] 40 | 41 | + Request (text/plain) 42 | 43 | All your base are belong to us. 44 | 45 | + Response 204 46 | -------------------------------------------------------------------------------- /examples/2. Resource and Actions.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Resource and Actions API 4 | This API example demonstrates how to define a resource with multiple actions. 5 | 6 | ## API Blueprint 7 | + [Previous: The Simplest API](1.%20Simplest%20API.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/2.%20Resource%20and%20Actions.md) 9 | + [Next: Named Resource and Actions](3.%20Named%20Resource%20and%20Actions.md) 10 | 11 | # /message 12 | This is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is defined by its [URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more precisely, by its [URI Template](http://tools.ietf.org/html/rfc6570). 13 | 14 | This resource has no actions specified but we will fix that soon. 15 | 16 | ## GET 17 | Here we define an action using the `GET` [HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`. 18 | 19 | As with every good action it should return a [response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always bears a status code. Code 200 is great as it means all is green. Responding with some data can be a great idea as well so let's add a plain text message to our response. 20 | 21 | + Response 200 (text/plain) 22 | 23 | Hello World! 24 | 25 | ## PUT 26 | OK, let's add another action. This time to put new data to our resource (essentially an update action). We will need to send something in a [request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a response back confirming the posting was a success (HTTP Status Code 204 ~ Resource updated successfully, no content is returned). 27 | 28 | + Request (text/plain) 29 | 30 | All your base are belong to us. 31 | 32 | + Response 204 33 | -------------------------------------------------------------------------------- /examples/6. Requests.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Requests API 4 | Following the [Responses](5.%20Responses.md) example, this API will show you how to define multiple requests and what data these requests can bear. Let's demonstrate multiple requests on a trivial example of content negotiation. 5 | 6 | ## API Blueprint 7 | + [Previous: Responses](5.%20Responses.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/6.%20Requests.md) 9 | + [Next: Parameters](7.%20Parameters.md) 10 | 11 | # Group Messages 12 | Group of all messages-related resources. 13 | 14 | ## My Message [/message] 15 | 16 | ### Retrieve a Message [GET] 17 | In API Blueprint requests can hold exactly the same kind of information and can be described by exactly the same structure as responses, only with different signature – using the `Request` keyword. The string that follows after the `Request` keyword is a request identifier. Again, using an explanatory and simple naming is the best way to go. 18 | 19 | + Request Plain Text Message 20 | 21 | + Headers 22 | 23 | Accept: text/plain 24 | 25 | + Response 200 (text/plain) 26 | 27 | + Headers 28 | 29 | X-My-Message-Header: 42 30 | 31 | + Body 32 | 33 | Hello World! 34 | 35 | + Request JSON Message 36 | 37 | + Headers 38 | 39 | Accept: application/json 40 | 41 | + Response 200 (application/json) 42 | 43 | + Headers 44 | 45 | X-My-Message-Header: 42 46 | 47 | + Body 48 | 49 | { "message": "Hello World!" } 50 | 51 | ### Update a Message [PUT] 52 | 53 | + Request Update Plain Text Message (text/plain) 54 | 55 | All your base are belong to us. 56 | 57 | + Request Update JSON Message (application/json) 58 | 59 | { "message": "All your base are belong to us." } 60 | 61 | + Response 204 62 | -------------------------------------------------------------------------------- /examples/8. Resource Model.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Resource Model API 4 | Resource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation). One particular represantation of your resource. 5 | 6 | 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`. 7 | 8 | ## API Blueprint 9 | + [Previous: Parameters](7.%20Parameters.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/8.%20Resource%20Model.md) 11 | 12 | # Group Messages 13 | Group of all messages-related resources. 14 | 15 | ## My Message [/message] 16 | 17 | + Model (application/vnd.siren+json) 18 | 19 | This is the `application/vnd.siren+json` message resource representation. 20 | 21 | + Headers 22 | 23 | Location: http://api.acme.com/message 24 | 25 | + Body 26 | 27 | { 28 | "class": [ "message" ], 29 | "properties": { 30 | "message": "Hello World!" 31 | }, 32 | "links": [ 33 | { "rel": "self" , "href": "/message" } 34 | ] 35 | } 36 | 37 | ### Retrieve a Message [GET] 38 | At this point we will utilize our `Message` resource model and reference it in `Response 200`. 39 | 40 | + Response 200 41 | 42 | [My Message][] 43 | 44 | ### Update a Message [PUT] 45 | 46 | + Request Update Plain Text Message (text/plain) 47 | 48 | All your base are belong to us. 49 | 50 | + Request Update JSON Message (application/json) 51 | 52 | { "message": "All your base are belong to us." } 53 | 54 | + Response 204 55 | 56 | -------------------------------------------------------------------------------- /examples/7. Parameters.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Parameters API 4 | In this installment of the API Blueprint course we will discuss how to describe API parameters. 5 | 6 | But first let's add more messages to our system. For that we would need introduce an message identifier – id. This id will be our parameter when communicating with our API about messages. 7 | 8 | ## API Blueprint 9 | + [Previous: Requests](6.%20Requests.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/7.%20Parameters.md) 11 | + [Next: Resource Model](8.%20Resource%20Model.md) 12 | 13 | # Group Messages 14 | Group of all messages-related resources. 15 | 16 | ## My Message [/message/{id}] 17 | Here we have added the message `id` parameter as an [URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message resource's URI. 18 | Note the parameter name `id` is enclosed in curly brackets. We will discuss this parameter in the `Parameters` section bellow, where we will also set its example value to `1` and declare it of an arbitrary 'number' type. 19 | 20 | + Parameters 21 | 22 | + id (number, `1`) ... An unique identifier of the message. 23 | 24 | ### Retrieve a Message [GET] 25 | 26 | + Request Plain Text Message 27 | 28 | + Headers 29 | 30 | Accept: text/plain 31 | 32 | + Response 200 (text/plain) 33 | 34 | + Headers 35 | 36 | X-My-Message-Header: 42 37 | 38 | + Body 39 | 40 | Hello World! 41 | 42 | + Request JSON Message 43 | 44 | + Headers 45 | 46 | Accept: application/json 47 | 48 | + Response 200 (application/json) 49 | 50 | + Headers 51 | 52 | X-My-Message-Header: 42 53 | 54 | + Body 55 | 56 | { 57 | "id": 1, 58 | "message": "Hello World!" 59 | } 60 | 61 | ### Update a Message [PUT] 62 | 63 | + Request Update Plain Text Message (text/plain) 64 | 65 | All your base are belong to us. 66 | 67 | + Request Update JSON Message (application/json) 68 | 69 | { "message": "All your base are belong to us." } 70 | 71 | + Response 204 72 | 73 | ## All My Messages [/messages{?limit}] 74 | A resource representing all of my messages in the system. 75 | 76 | We have added the query URI template parameter - `limit`. This parameter is used for limiting the number of results returned by some actions on this resource. It does not affect every possible action of this resource therefore we will discuss it only at the particular action level below. 77 | 78 | ### Retrieve all Messages [GET] 79 | 80 | + Parameters 81 | 82 | + limit = `20` (optional, number) ... The maximum number of results to return. 83 | 84 | + Response 200 (application/json) 85 | 86 | [ 87 | { 88 | "id": 1, 89 | "message": "Hello World!" 90 | }, 91 | { 92 | "id": 2, 93 | "message": "Time is an illusion. Lunchtime doubly so." 94 | }, 95 | { 96 | "id": 3, 97 | "message": "So long, and thanks for all the fish." 98 | } 99 | ] 100 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![logo](https://raw.github.com/apiaryio/api-blueprint/master/assets/logo_apiblueprint.png) 2 | 3 | # API Blueprint 4 | ### API Design for Humans 5 | API Blueprint is a documentation-oriented API description language. A couple of semantical assumptions over the plain [Markdown](http://daringfireball.net/projects/markdown/). 6 | 7 | API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. 8 | 9 | API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not. 10 | 11 | ## TL;DR 12 | + Web API description language 13 | + Pure Markdown 14 | + Designed for humans 15 | + Understandable by machines 16 | + Open & free 17 | 18 | ## Getting started with API Blueprint 19 | All it takes to describe that `message` endpoint of your API is to write: 20 | 21 | ```md 22 | # GET /message 23 | + Response 200 (text/plain) 24 | 25 | Hello World! 26 | ``` 27 | 28 | in your favorite Markdown editor. With this API description in your API GitHub repository you can discuss it with others and iterate on your API Design. 29 | 30 | To learn more about the API Blueprint syntax jump directly to the [API Blueprint Tutorial](Tutorial.md) or take a look at some [examples](https://github.com/apiaryio/api-blueprint/tree/master/examples). 31 | 32 | ## Complete Lifecycle 33 | Describing your API is only the start. The API Blueprint can be used by variety of tools from an interactive documentation, SDK generator, debugging proxy and mock server to API testing and analytics tools. 34 | 35 | ![API Blueprint Lifecycle](assets/lifecycle.png) 36 | 37 | Visit the [tooling section](http://apiblueprint.org/#tooling) of the API Blueprint website to find more about the tools you can use with API Blueprint. 38 | 39 | 40 | ## Machines 41 | Building tools for API Blueprint is possible thanks to its machine-friendly face: 42 | 43 | ```json 44 | { 45 | "_version": "2.0", 46 | "metadata": [], 47 | "name": "", 48 | "description": "", 49 | 50 | ... 51 | ``` 52 | \[[full listing](https://github.com/apiaryio/api-blueprint-ast#json-serialization)\] 53 | 54 | It is the task for the API Blueprint parser – [Snow Crash][] or one of its language bindings to translate the API Blueprint Markdown representation into a machine friendly format – AST. 55 | 56 | If you are interested in building tools for API Blueprint or just to integrate it with your workflow check out the [Developing tools for API Blueprint](https://github.com/apiaryio/api-blueprint/wiki/Developing-tools-for-API-Blueprint). 57 | 58 | ## Learn more 59 | + [Tutorial](Tutorial.md) 60 | + [Examples](examples) 61 | + [Glossary of Terms](Glossary%20of%20Terms.md) 62 | + [API Blueprint Map](https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map) 63 | + [Language Specification](API%20Blueprint%20Specification.md) 64 | + [Tools working with API Blueprint](http://apiblueprint.org/#tooling) 65 | 66 | ### Developers 67 | + [API Blueprint reference parser – Snow Crash](https://github.com/apiaryio/snowcrash) 68 | + [Snow Crash Bindings to other languages](https://github.com/apiaryio/snowcrash#bindings) 69 | + [API Blueprint AST Serialization Media Types](https://github.com/apiaryio/api-blueprint-ast) 70 | + [Developing tools for API Blueprint](https://github.com/apiaryio/api-blueprint/wiki/Developing-tools-for-API-Blueprint) 71 | 72 | ## Future of API Blueprint 73 | Check out the API Blueprint [Issues Page](https://github.com/apiaryio/api-blueprint/issues) for planned features and issues discussion. 74 | 75 | ## Contribute 76 | Fork & pull request. 77 | 78 | ## Have a question? 79 | Ask at [Stack Overflow](http://stackoverflow.com/questions/tagged/apiblueprint), make sure to use the `apiblueprint` tag. Alternatively mention [@apiblueprint](https://twitter.com/apiblueprint) on Twitter. 80 | 81 | ## License 82 | MIT License. See the [LICENSE](https://github.com/apiaryio/api-blueprint/blob/master/LICENSE) file. 83 | 84 | [Snow Crash]: https://github.com/apiaryio/snowcrash 85 | -------------------------------------------------------------------------------- /examples/Real World API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | HOST: https://alpha-api.app.net 3 | 4 | # Real World API 5 | This API Blueprint demonstrates a real world example documenting a portion of [App.net API](http://developers.app.net). 6 | 7 | NOTE: This document is a **work in progress**. 8 | 9 | # Group Posts 10 | This section groups App.net post resources. 11 | 12 | ## Post [/stream/0/posts/{post_id}] 13 | A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph... 14 | 15 | + Parameters 16 | + post_id (string, `1`) ... The id of the Post. 17 | 18 | + Model (application/json) 19 | 20 | ```js 21 | { 22 | "data": { 23 | "id": "1", // note this is a string 24 | "user": { 25 | ... 26 | }, 27 | "created_at": "2012-07-16T17:25:47Z", 28 | "text": "@berg FIRST post on this new site #newsocialnetwork", 29 | "html": "@berg FIRST post on this new site #newsocialnetwork.", 30 | "source": { 31 | "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4", 32 | "name": "Clientastic for iOS", 33 | "link": "http://app.net" 34 | }, 35 | "machine_only": false, 36 | "reply_to": null, 37 | "thread_id": "1", 38 | "num_replies": 3, 39 | "num_reposts": 0, 40 | "num_stars": 0, 41 | "entities": { 42 | "mentions": [{ 43 | "name": "berg", 44 | "id": "2", 45 | "pos": 0, 46 | "len": 5 47 | }], 48 | "hashtags": [{ 49 | "name": "newsocialnetwork", 50 | "pos": 34, 51 | "len": 17 52 | }], 53 | "links": [{ 54 | "text": "this new site", 55 | "url": "https://join.app.net" 56 | "pos": 20, 57 | "len": 13 58 | }] 59 | }, 60 | "you_reposted": false, 61 | "you_starred": false 62 | }, 63 | "meta": { 64 | "code": 200, 65 | } 66 | } 67 | ``` 68 | 69 | ### Retrieve a Post [GET] 70 | Returns a specific Post. 71 | 72 | + Response 200 73 | 74 | [Post][] 75 | 76 | ### Delete a Post [DELETE] 77 | Delete a Post. The current user must be the same user who created the Post. It returns the deleted Post on success. 78 | 79 | + Response 204 80 | 81 | ## Posts Collection [/stream/0/posts] 82 | A Collection of posts. 83 | 84 | + Model (application/json) 85 | 86 | ```js 87 | { 88 | "data": [ 89 | { 90 | "id": "1", // note this is a string 91 | ... 92 | }, 93 | { 94 | "id": "2", 95 | ... 96 | }, 97 | { 98 | "id": "3", 99 | ... 100 | }, 101 | ], 102 | "meta": { 103 | "code": 200, 104 | } 105 | } 106 | ``` 107 | 108 | ### Create a Post [POST] 109 | Create a new Post object. Mentions and hashtags will be parsed out of the post text, as will bare URLs... 110 | 111 | + Request 112 | 113 | [Post][] 114 | 115 | + Response 201 116 | 117 | [Post][] 118 | 119 | ### Retrieve all Posts [GET] 120 | Retrieves all posts. 121 | 122 | + Response 200 123 | 124 | [Posts Collection][] 125 | 126 | ## Stars [/stream/0/posts/{post_id}/star] 127 | A User’s stars are visible to others, but they are not automatically added to your followers’ streams. 128 | 129 | + Parameters 130 | + post_id (string, `1`) ... The id of the Post. 131 | 132 | ### Star a Post [POST] 133 | Save a given Post to the current User’s stars. This is just a “save” action, not a sharing action. 134 | 135 | *Note: A repost cannot be starred. Please star the parent Post.* 136 | 137 | + Response 200 138 | 139 | [Post][] 140 | 141 | ### Unstar a Post [DELETE] 142 | Remove a Star from a Post. 143 | 144 | + Response 200 145 | 146 | [Post][] 147 | -------------------------------------------------------------------------------- /Glossary of Terms.md: -------------------------------------------------------------------------------- 1 | # API Blueprint Glossary of Terms 2 | 3 | A brief list of terms as used in the [API Blueprint](http://apiblueprint.org) context. 4 | 5 | ## Glossary 6 | 7 | 8 | ### Action 9 | An **HTTP transaction** (a request-response transaction). 10 | 11 | Actions are specified by an [HTTP request method](#def-method) within a [resource](#def-resource). 12 | 13 | 14 | ### API 15 | An **HTTP Application programming interface**. Might refer to an API description. See [**API Blueprint**](#def-api-blueprint). 16 | 17 | 18 | ### API Blueprint 19 | The **API Blueprint language**. A format used to describe API in an API blueprint file. 20 | 21 | 22 | ### Asset 23 | **Atomic data**. Most often representing one resource representation in the form of message-body or its validation schema. 24 | 25 | 26 | ### Blueprint 27 | An **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language. 28 | 29 | 30 | ### Entity 31 | [**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload). 32 | 33 | 34 | ### Header 35 | A [**message-header**](#def-message-header). 36 | 37 | 38 | ### Method 39 | An [**HTTP Request Method**](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods). 40 | 41 | 42 | ### Message 43 | An **HTTP transaction message**. 44 | 45 | 46 | ### Message body 47 | An [**asset**](#def-asset) representing [**HTTP transaction message body**](http://en.wikipedia.org/wiki/HTTP_body_data). 48 | 49 | 50 | ### Message header 51 | An [**asset**](#def-asset) representing [**HTTP transaction message header**](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields). 52 | 53 | ### Parameter 54 | An [**URI template**](#def-uri-template) **variable**. 55 | 56 | 57 | ### Payload 58 | An **HTTP transaction message** including its **discussion** and any additional [**assets**](#def-asset) such as entity-body validation schema. 59 | 60 | A payload may have its **identifier** – a string for a [request](#def-request) payload or an [HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for a [response](#def-response) payload. 61 | 62 | 63 | ### Property 64 | An [entinty](#def-entity) field (attribute). 65 | 66 | 67 | ### Request 68 | A [**payload**](#def-payload) containing one specific [HTTP Request](http://www.w3.org/TR/di-gloss/#def-http-request). 69 | 70 | 71 | ### Response 72 | A [**payload**](#def-payload) containing one specific [HTTP Response](http://www.w3.org/TR/di-gloss/#def-http-response). 73 | 74 | 75 | ### Resource 76 | An API [**resource**](http://www.w3.org/TR/di-gloss/#def-resource) specified by its *URI*. It can also refer to a [**set of resources**](#def-resource) matching one [**URI template**](#def-uri-template). 77 | 78 | 79 | ### Resource Model 80 | One [**manifestation of a resource**](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) in the form of a [payload](#def-payload). A resource model is an example representation of its resource. Can be referenced later in the place of a [payload](#def-payload). 81 | 82 | 83 | ### Resource Set 84 | A set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource) its *URI* matches one specific [**URI template**](#def-uri-template). 85 | 86 | 87 | ### Trait 88 | A quality or characteristic of an API Blueprint SECTION. 89 | 90 | 91 | ### Schema 92 | A **validation schema** in a form of an [**asset**](#def-asset) used to validate (or describe) a [**message-body**](#def-message-body). 93 | 94 | 95 | ### URI template 96 | A compact sequence of characters for describing a range of **Uniform Resource Identifiers** through **variable** expansion, see [**RFC 6570**](http://tools.ietf.org/html/rfc6570). 97 | 98 | ## Additional resources 99 | 100 | + [HTTP/1.1 Terminology](http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3) 101 | + [W3C Glossary of Terms for Device Independence](http://www.w3.org/TR/di-gloss) 102 | + [Know your HTTP well](https://github.com/for-GET/know-your-http-well) 103 | -------------------------------------------------------------------------------- /examples/Gist Fox API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Gist Fox API 4 | Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com). 5 | 6 | ## Authentication 7 | Currently the Gist Fox API does not provide authenticated access. 8 | 9 | ## Media Types 10 | Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances. 11 | 12 | Requests with a message-body are using plain JSON to set or update resource states. 13 | 14 | ## Error States 15 | The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used. 16 | 17 | # Gist Fox API Root [/] 18 | Gist Fox API entry point. 19 | 20 | This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and 21 | HAL links. 22 | 23 | ## Retrieve the Entry Point [GET] 24 | 25 | + Response 200 (application/hal+json) 26 | + Headers 27 | 28 | Link: ;rel="self",;rel="gists" 29 | 30 | + Body 31 | 32 | { 33 | "_links": { 34 | "self": { "href": "/" }, 35 | "gists": { "href": "/gists?{since}", "templated": true } 36 | } 37 | } 38 | 39 | # Group Gist 40 | Gist-related resources of *Gist Fox API*. 41 | 42 | ## Gist [/gists/{id}] 43 | A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note. 44 | 45 | The Gist resource has the following attributes: 46 | 47 | - id 48 | - created_at 49 | - description 50 | - content 51 | 52 | The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation. 53 | 54 | 55 | + Parameters 56 | + id (string) ... ID of the Gist in the form of a hash. 57 | 58 | + Model (application/hal+json) 59 | 60 | HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links. 61 | 62 | + Headers 63 | 64 | Link: ;rel="self", ;rel="star" 65 | 66 | + Body 67 | 68 | { 69 | "_links": { 70 | "self": { "href": "/gists/42" }, 71 | "star": { "href": "/gists/42/star" }, 72 | }, 73 | "id": "42", 74 | "created_at": "2014-04-14T02:15:15Z", 75 | "description": "Description of Gist", 76 | "content": "String contents" 77 | } 78 | 79 | ### Retrieve a Single Gist [GET] 80 | + Response 200 81 | 82 | [Gist][] 83 | 84 | ### Edit a Gist [PATCH] 85 | To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash. 86 | 87 | + Request (application/json) 88 | 89 | { 90 | "content": "Updated file contents" 91 | } 92 | 93 | + Response 200 94 | 95 | [Gist][] 96 | 97 | ### Delete a Gist [DELETE] 98 | + Response 204 99 | 100 | ## Gists Collection [/gists{?since}] 101 | Collection of all Gists. 102 | 103 | The Gist Collection resource has the following attribute: 104 | 105 | - total 106 | 107 | In addition it **embeds** *Gist Resources* in the Gist Fox API. 108 | 109 | 110 | + Model (application/hal+json) 111 | 112 | HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation. 113 | 114 | + Headers 115 | 116 | Link: ;rel="self" 117 | 118 | + Body 119 | 120 | { 121 | "_links": { 122 | "self": { "href": "/gists" } 123 | }, 124 | "_embedded": { 125 | "gists": [ 126 | { 127 | "_links" : { 128 | "self": { "href": "/gists/42" } 129 | }, 130 | "id": "42", 131 | "created_at": "2014-04-14T02:15:15Z", 132 | "description": "Description of Gist" 133 | } 134 | ] 135 | }, 136 | "total": 1 137 | } 138 | 139 | ### List All Gists [GET] 140 | + Parameters 141 | + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. 142 | 143 | + Response 200 144 | 145 | [Gists Collection][] 146 | 147 | ### Create a Gist [POST] 148 | To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 149 | 150 | + Request (application/json) 151 | 152 | { 153 | "description": "Description of Gist", 154 | "content": "String content" 155 | } 156 | 157 | + Response 201 158 | 159 | [Gist][] 160 | 161 | ## Star [/gists/{id}/star] 162 | Star resource represents a Gist starred status. 163 | 164 | The Star resource has the following attribute: 165 | 166 | - starred 167 | 168 | 169 | + Parameters 170 | 171 | + id (string) ... ID of the gist in the form of a hash 172 | 173 | + Model (application/hal+json) 174 | 175 | HAL+JSON representation of Star Resource. 176 | 177 | + Headers 178 | 179 | Link: ;rel="self" 180 | 181 | + Body 182 | 183 | { 184 | "_links": { 185 | "self": { "href": "/gists/42/star" }, 186 | }, 187 | "starred": true 188 | } 189 | 190 | ### Star a Gist [PUT] 191 | + Response 204 192 | 193 | ### Unstar a Gist [DELETE] 194 | + Response 204 195 | 196 | ### Check if a Gist is Starred [GET] 197 | + Response 200 198 | 199 | [Star][] 200 | -------------------------------------------------------------------------------- /examples/Gist Fox API + Auth.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Gist Fox API 4 | Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com). 5 | 6 | ## Authentication 7 | *Gist Fox API* uses OAuth Authorization. First you create a new (or acquire existing) OAuth token using Basic Authentication. After you have acquired your token you can use it to access other resources within token' scope. 8 | 9 | ## Media Types 10 | Where applicable this API uses the [HAL+JSON](https://github.com/mikekelly/hal_specification/blob/master/hal_specification.md) media-type to represent resources states and affordances. 11 | 12 | Requests with a message-body are using plain JSON to set or update resource states. 13 | 14 | ## Error States 15 | The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) are used. 16 | 17 | # Gist Fox API Root [/] 18 | Gist Fox API entry point. 19 | 20 | This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and 21 | HAL links. 22 | 23 | ## Retrieve the Entry Point [GET] 24 | 25 | + Response 200 (application/hal+json) 26 | + Headers 27 | 28 | Link: ;rel="self",;rel="gists",;rel="authorization" 29 | 30 | + Body 31 | 32 | { 33 | "_links": { 34 | "self": { "href": "/" }, 35 | "gists": { "href": "/gists?{since}", "templated": true } 36 | "authorization": { "href": "/authorization"} 37 | } 38 | } 39 | 40 | # Group Gist 41 | Gist-related resources of *Gist Fox API*. 42 | 43 | ## Gist [/gists/{id}{?access_token}] 44 | A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note. 45 | 46 | The Gist resource has the following attributes: 47 | 48 | - id 49 | - created_at 50 | - description 51 | - content 52 | 53 | The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation. 54 | 55 | + Parameters 56 | + id (string) ... ID of the Gist in the form of a hash. 57 | + access_token (string, optional) ... Gist Fox API access token. 58 | 59 | + Model (application/hal+json) 60 | 61 | HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links. 62 | 63 | + Headers 64 | 65 | Link: ;rel="self", ;rel="star" 66 | 67 | + Body 68 | 69 | { 70 | "_links": { 71 | "self": { "href": "/gists/42" }, 72 | "star": { "href": "/gists/42/star" }, 73 | }, 74 | "id": "42", 75 | "created_at": "2014-04-14T02:15:15Z", 76 | "description": "Description of Gist", 77 | "content": "String contents" 78 | } 79 | 80 | ### Retrieve a Single Gist [GET] 81 | + Response 200 82 | 83 | [Gist][] 84 | 85 | ### Edit a Gist [PATCH] 86 | To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash. 87 | 88 | + Request (application/json) 89 | 90 | { 91 | "content": "Updated file contents" 92 | } 93 | 94 | + Response 200 95 | 96 | [Gist][] 97 | 98 | ### Delete a Gist [DELETE] 99 | + Response 204 100 | 101 | ## Gists Collection [/gists{?access_token,since}] 102 | Collection of all Gists. 103 | 104 | The Gist Collection resource has the following attribute: 105 | 106 | - total 107 | 108 | In addition it **embeds** *Gist Resources* in the Gist Fox API. 109 | 110 | + Model (application/hal+json) 111 | 112 | HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation. 113 | 114 | + Headers 115 | 116 | Link: ;rel="self" 117 | 118 | + Body 119 | 120 | { 121 | "_links": { 122 | "self": { "href": "/gists" } 123 | }, 124 | "_embedded": { 125 | "gists": [ 126 | { 127 | "_links" : { 128 | "self": { "href": "/gists/42" } 129 | }, 130 | "id": "42", 131 | "created_at": "2014-04-14T02:15:15Z", 132 | "description": "Description of Gist" 133 | } 134 | ] 135 | }, 136 | "total": 1 137 | } 138 | 139 | ### List All Gists [GET] 140 | + Parameters 141 | + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only gists updated at or after this time are returned. 142 | 143 | + Response 200 144 | 145 | [Gists Collection][] 146 | 147 | ### Create a Gist [POST] 148 | To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 149 | 150 | This action requries an `access_token` with `gist_write` scope. 151 | 152 | + Parameters 153 | + access_token (string, optional) ... Gist Fox API access token. 154 | 155 | + Request (application/json) 156 | 157 | { 158 | "description": "Description of Gist", 159 | "content": "String content" 160 | } 161 | 162 | + Response 201 163 | 164 | [Gist][] 165 | 166 | ## Star [/gists/{id}/star{?access_token}] 167 | Star resource represents a Gist starred status. 168 | 169 | The Star resource has the following attribute: 170 | 171 | - starred 172 | 173 | + Parameters 174 | + id (string) ... ID of the gist in the form of a hash 175 | + access_token (string, optional) ... Gist Fox API access token. 176 | 177 | + Model (application/hal+json) 178 | 179 | HAL+JSON representation of Star Resource. 180 | 181 | + Headers 182 | 183 | Link: ;rel="self" 184 | 185 | + Body 186 | 187 | { 188 | "_links": { 189 | "self": { "href": "/gists/42/star" }, 190 | }, 191 | "starred": true 192 | } 193 | 194 | ### Star a Gist [PUT] 195 | This action requries an `access_token` with `gist_write` scope. 196 | 197 | + Response 204 198 | 199 | ### Unstar a Gist [DELETE] 200 | This action requries an `access_token` with `gist_write` scope. 201 | 202 | + Response 204 203 | 204 | ### Check if a Gist is Starred [GET] 205 | + Response 200 206 | 207 | [Star][] 208 | 209 | # Group Access Authorization and Control 210 | Access and Control of *Gist Fox API* OAuth token. 211 | 212 | ## Authorization [/authorization] 213 | Authorization Resource represents an authorization granted to the user. You can **only** access your own authorization, and only through **Basic Authentication**. 214 | 215 | The Authorization Resource has the following attribute: 216 | 217 | - token 218 | - scopes 219 | 220 | Where *token* represents an OAuth token and *scopes* is an array of scopes granted for the given authorization. At this moment the only available scope is `gist_write`. 221 | 222 | + Model (application/hal+json) 223 | 224 | + Headers 225 | 226 | Link: ;rel="self" 227 | 228 | + Body 229 | 230 | { 231 | "_links": { 232 | "self": { "href": "/authorizations" }, 233 | }, 234 | "scopes": [ 235 | "gist_write" 236 | ], 237 | "token": "abc123" 238 | } 239 | 240 | ### Retrieve Authorization [GET] 241 | + Request 242 | + Headers 243 | 244 | Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 245 | 246 | + Response 200 247 | 248 | [Authorization][] 249 | 250 | ### Create Authorization [POST] 251 | + Request (application/json) 252 | + Headers 253 | 254 | Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 255 | 256 | + Body 257 | 258 | { 259 | "scopes": [ 260 | "gist_write" 261 | ] 262 | } 263 | 264 | + Response 201 265 | 266 | [Authorization][] 267 | 268 | ### Remove an Authorization [DELETE] 269 | + Request 270 | + Headers 271 | 272 | Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== 273 | 274 | + Response 204 275 | -------------------------------------------------------------------------------- /Tutorial.md: -------------------------------------------------------------------------------- 1 | # API Blueprint Tutorial 2 | Welcome to the API Blueprint Tutorial! In this tutorial you will learn all about all the key features of the API Blueprint Language on the example of an API for our imaginary industry-changing Gist service. 3 | 4 | Gist is a paste. A snippet of text. Not unrelated to [GitHub Gists][]. To set some expectations let's provide following functionality in our API: *List Gists, Retrieve a Single Gist, Create a Gist, Edit a Gist, Star a Gist, Unstar a Gist, Check if a Gist is starred and Delete a Gist.* 5 | 6 | > **Note:** **Additional API Blueprint Resources** 7 | > 8 | > + [Language Specification][specification] 9 | > + [Examples][API Blueprint Examples] 10 | > + [Glossary of Terms][API Blueprint Glossary of Terms] 11 | > + [API Blueprint Map][map] 12 | > + [Tools for API Blueprint][Tooling Section] 13 | 14 | ## Gist Fox API 15 | Without any further ado our *Gist Fox API* blueprint starts like this: 16 | 17 | FORMAT: 1A 18 | 19 | # Gist Fox API 20 | Gist Fox API is a **pastes service** similar to [GitHub's Gist][http://gist.github.com]. 21 | 22 | What have we just done? Let's break it line by line: 23 | 24 | #### Metadata 25 | 26 | FORMAT: 1A 27 | 28 | Depending on the tools you will be using with your blueprint you might want to start your blueprint file with a metadata explicitly stating the API Blueprint version you want to use like in this case the version 1A. 29 | 30 | > **Note:** Should you need a clarification of some terms as used through this document refer to [API Blueprint Glossary of Terms][]. 31 | 32 | #### API Name 33 | 34 | # Gist Fox API 35 | 36 | Every good API should have a name. So does ours – *"Gist Fox API"*. The first Markdown header in our document represents just that – the API name. 37 | 38 | #### API Description 39 | 40 | Gist Fox API is a **pastes service** similar to [GitHub's Gist][http://gist.github.com]. 41 | 42 | The API Name might be followed by any arbitrary Markdown-formatted discussion. Preferably about your API. 43 | 44 | > **Note:** We will add much richer and more helpful discussion in the final version of this blueprint. Adding details about authentication, used media types and error handling to API description is always a great idea! 45 | > 46 | > **Note:** For the sake of simplicity we will now omit user management and authentication. These features will be discussed in a future installment of the API Blueprint Tutorial. 47 | 48 | ## Markdown 49 | All you really need to write a blueprint is a text editor. A Markdown editor is even better. Anything you like. From Vi to Byword. Online editors are great too! You can even directly edit a blueprint on GitHub in the repository your service is living! 50 | 51 | If you are completely new to Markdown it is now the best time to learn about it. Just head over to [Markdown Tutorial][] and enjoy the ride. Just don't forget to come back we have some cool stuff too! 52 | 53 | Should you just need to refresh Markdown syntax you can always check the one and only [Gruber's Original][] documentation. 54 | 55 | > **Note:** It is not essentially required to know the Markdown syntax but it will help you a lot. The knowledge of Markdown will make some API Blueprint constructs more intuitive. 56 | 57 | ## First Resource 58 | The first resource in our API is its root. The entry point to our API is defined like so: 59 | 60 | # Gist Fox API Root [/] 61 | Gist Fox API entry point. 62 | 63 | This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and HAL links. 64 | 65 | ## Retrieve Entry Point [GET] 66 | 67 | + Response 200 (application/hal+json) 68 | + Headers 69 | 70 | Link: ;rel="self",;rel="gists" 71 | 72 | + Body 73 | 74 | { 75 | "_links": { 76 | "self": { "href": "/" }, 77 | "gists": { "href": "/gists?{since}", "templated": true } 78 | } 79 | } 80 | 81 | What is going on here? 82 | 83 | #### Resource 84 | 85 | # Gist Fox API Root [/] 86 | 87 | In API Blueprint a resource definition starts with a Markdown header with the resource name followed by its URI enclosed in square brackets. The URI is relative to the API root. So in this case it is just `/`. 88 | 89 | > **NOTE:** Resource name is an [API Blueprint Identifier][] and as such it can be composed only from a combination of alphanumerical characters, underscores, dashes and a spaces. 90 | 91 | #### Resource Description 92 | 93 | # Gist Fox API Root [/] 94 | Gist Fox API entry point. 95 | 96 | This resource does not have any attributes. Instead it offers the initial API affordances in the form of the HTTP Link header and haveL links. 97 | 98 | As with the API Name the resource name can be followed by an arbitrary Markdown formatted description. 99 | 100 | #### Action 101 | 102 | ## Retrieve Entry Point [GET] 103 | 104 | Here we have just defined an action named "Retrieve Entry Point" utilizing the `GET` [HTTP Request Method][]. As with a resource and API name we can add any arbitrary description here but since the action name is pretty self explanatory we will skip it for now. 105 | 106 | #### Response 107 | 108 | + Response 200 109 | 110 | In API Blueprint an action **should** always include at least one response representing the HTTP response message sent back in response to a HTTP request. The response should always bear a [status code][] and possibly an additional [payload][]. Here we have defined the most common response "200" indicating the request has succeeded. 111 | 112 | #### Response Payload 113 | 114 | + Response 200 (application/hal+json) 115 | + Headers 116 | 117 | Link: ;rel="self",;rel="gists" 118 | 119 | + Body 120 | 121 | { 122 | "_links": { 123 | "self": { "href": "/" }, 124 | "gists": { "href": "/gists?{since}", "templated": true } 125 | } 126 | } 127 | 128 | A response usually bears some payload sent to our client. Ideally it details the resource in question. In this case our response representation is of the [`application/hal+json`][] media-type. Also in addition to an HTTP response message-body this response defines an HTTP response [message-headers][] in its payload. 129 | 130 | > **Note:** API Blueprint is **indentation sensitive**. See the [Note on Indentation][] for details. 131 | > 132 | > **Note:** Specifying the media type in parenthesis after the response status codes generates implicit `Content-Type` HTTP header. Therefore you do not have to explicitly specify the `Content-Type` header. 133 | > 134 | > **Note:** If your response does not need to define any additional headers (but `Content-Type`) you can skip the `Headers` section completely and write the `Body` section like so: 135 | > 136 | > + Response 200 (application/hal+json) 137 | > 138 | > { 139 | > "_links": { 140 | > "self": { "href": "/" }, 141 | > "gists": { "href": "/gists?{since}", "templated": true } 142 | > } 143 | > } 144 | 145 | ## Complex Resource 146 | With the entry point of our API defined we can move forward. Since our API revolves around a Gist let's define its representation and an action to retrieve it: 147 | 148 | # Group Gist 149 | Gist-related resources of *Gist Fox API*. 150 | 151 | ## Gist [/gists/{id}] 152 | A single Gist object. The Gist resource is the central resource in the Gist Fox API. It represents one paste - a single text note. 153 | 154 | The Gist resource has the following attributes: 155 | 156 | - id 157 | - created_at 158 | - description 159 | - content 160 | 161 | The states *id* and *created_at* are assigned by the Gist Fox API at the moment of creation. 162 | 163 | 164 | + Parameters 165 | + id (string) ... ID of the Gist in the form of a hash. 166 | 167 | + Model (application/hal+json) 168 | 169 | HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links. 170 | 171 | + Headers 172 | 173 | Link: ;rel="self", ;rel="star" 174 | 175 | + Body 176 | 177 | { 178 | "_links": { 179 | "self": { "href": "/gists/42" }, 180 | "star": { "href": "/gists/42/star" }, 181 | }, 182 | "id": "42", 183 | "created_at": "2014-04-14T02:15:15Z", 184 | "description": "Description of Gist", 185 | "content": "String contents" 186 | } 187 | 188 | ### Retrieve a Single Gist [GET] 189 | + Response 200 190 | 191 | [Gist][] 192 | 193 | Here we have just defined a **Group** of our Gist-related resources. We have also defined a **Gist resource**, its **model representation** and **an action** that retrieves a single Gist. 194 | 195 | Let's break it down to what's new: 196 | 197 | #### Groups of Resources 198 | 199 | # Group Gist 200 | Gist-related resources of *Gist Fox API*. 201 | 202 | As our API will eventually provide more resources it is a good practice to group related resources together for better orientation. Here we will be grouping all Gist-related resources under a group simply called the *"Gist"*. Groups get recognized from a header with **Group** keyword at the beginning of its text. 203 | 204 | #### URI Template 205 | 206 | ## Gist [/gists/{id}] 207 | 208 | A variable component of a Gist URI expressed in the form of [URI Template][]. In this case an id of Gist is the URI variable expressed as `{id}`. 209 | 210 | 211 | #### URI Parameters 212 | 213 | + Parameters 214 | + id (string) ... ID of the Gist in the form of a hash. 215 | 216 | The *"id"* variable of the URI template is a parameter to every action on this resource. Here defined of an arbitrary type *"string"* and followed by its Markdown-formatted discussion. 217 | 218 | > **Note:** You can specify various attributes of an URI parameter. But in its simple form the URI parameter syntax is just the parameter name followed by ellipsis (three dots) and a Markdown-formatted discussion. For example: 219 | > 220 | > + Parameters 221 | > + id ... description 222 | > 223 | > Refer to API Blueprint Specification's [Resource Parameters Section][] for additional examples. 224 | 225 | 226 | #### Resource Model 227 | 228 | + Model (application/hal+json) 229 | 230 | HAL+JSON representation of Gist Resource. In addition to representing its state in the JSON form it offers affordances in the form of the HTTP Link header and HAL links. 231 | 232 | + Headers 233 | 234 | Link: ;rel="self", ;rel="star" 235 | 236 | + Body 237 | 238 | { 239 | "_links": { 240 | "self": { "href": "/gists/42" }, 241 | "star": { "href": "/gists/42/star" }, 242 | }, 243 | "id": "42", 244 | "created_at": "2014-04-14T02:15:15Z", 245 | "description": "Description of Gist", 246 | "content": "String contents" 247 | } 248 | 249 | Resource Model is an example representation of the Gist resource. It can be referenced later at any point where a response (or request) payload is expected. A resource model has *exactly* the same structure as a response payload. In this case it also includes additional description. A Resource Model may not include a response status code. 250 | 251 | 252 | #### Referring the Resource Model 253 | 254 | ### Retrieve a Single Gist [GET] 255 | + Response 200 256 | 257 | [Gist][] 258 | 259 | With Gist Resource Model in place it is super easy to define an action that retrieves a single gist. 260 | 261 | > **NOTE:** The syntax for referencing a resource model is `[][]`. You can only refer to *already defined models*. The model must be referred as "whole" - you can't reuse just a model's body or headers. 262 | 263 | ## Modifying a Resource 264 | Let's add an action to our Gist Resource that will allow us to modify its state and another action that deletes a Gist Resource as whole. 265 | 266 | ### Edit a Gist [PATCH] 267 | To update a Gist send a JSON with updated value for one or more of the Gist resource attributes. All attributes values (states) from the previous version of this Gist are carried over by default if not included in the hash. 268 | 269 | + Request (application/json) 270 | 271 | { 272 | "content": "Updated file contents" 273 | } 274 | 275 | + Response 200 276 | 277 | [Gist][] 278 | 279 | ### Delete a Gist [DELETE] 280 | + Response 204 281 | 282 | Here are a few new things to learn about payloads: 283 | 284 | #### Request and its Payload 285 | 286 | + Request (application/json) 287 | 288 | { 289 | "content": "Updated file contents" 290 | } 291 | 292 | Our "Edit a Gist" action needs to receive some input data to update the state of the Gist resource with it. The data are part of an HTTP request message. This section defines such a Request and an example [payload][] of the request message. 293 | 294 | > **NOTE:** The Request follows exactly the same structure as a Response or Model. As with the Resource Model a Request may not include a response status code. 295 | 296 | #### Empty Payload 297 | 298 | ### Delete a Gist [DELETE] 299 | + Response 204 300 | 301 | In the case of the "Delete a Gist" action our response bears status code "204" indicating the server has successfully fulfilled the request and that there is no additional content to be send in the response payload body. 302 | 303 | ## Collection Resource 304 | With single the Gist Resource in place let's define the collection of our Gist Resources: 305 | 306 | ## Gists Collection [/gists{?since}] 307 | Collection of all Gists. 308 | 309 | The Gist Collection resource has the following attribute: 310 | 311 | - total 312 | 313 | In addition it **embeds** *Gist Resources* in the Gist Fox API. 314 | 315 | 316 | + Model (application/hal+json) 317 | 318 | HAL+JSON representation of Gist Collection Resource. The Gist resources in collections are embedded. Note the embedded Gists resource are incomplete representations of the Gist in question. Use the respective Gist link to retrieve its full representation. 319 | 320 | + Headers 321 | 322 | Link: ;rel="self" 323 | 324 | + Body 325 | 326 | { 327 | "_links": { 328 | "self": { "href": "/gists" } 329 | }, 330 | "_embedded": { 331 | "gists": [ 332 | { 333 | "_links" : { 334 | "self": { "href": "/gists/42" } 335 | }, 336 | "id": "42", 337 | "created_at": "2014-04-14T02:15:15Z", 338 | "description": "Description of Gist" 339 | } 340 | ] 341 | }, 342 | "total": 1 343 | } 344 | 345 | ### List All Gists [GET] 346 | + Parameters 347 | + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only Gists updated at or after this time are returned. 348 | 349 | + Response 200 350 | 351 | [Gists Collection][] 352 | 353 | ### Create a Gist [POST] 354 | To create a new Gist simply provide a JSON hash of the *description* and *content* attributes for the new Gist. 355 | 356 | + Request (application/json) 357 | 358 | { 359 | "description": "Description of Gist", 360 | "content": "String content" 361 | } 362 | 363 | + Response 201 (application/hal+json) 364 | 365 | [Gist][] 366 | 367 | At this point you should be familiar with everything in this listing except the definition and discussion of the query parameter *"since"*: 368 | 369 | 370 | #### Query Parameters 371 | 372 | ## Gists Collection [/gists{?since}] 373 | 374 | As with the URI parameters the Query parameters are defined in the [URI Template][] format. The difference here is that a query parameter name is preceded by the *question mark* and it is always at the end of the URI Template. 375 | 376 | > **NOTE:** To define multiple query parameters simply comma-separate their names. For example `{?month,year}`. 377 | 378 | #### Action-specific Query Parameters 379 | 380 | ### List All Gists [GET] 381 | + Parameters 382 | + since (optional, string) ... Timestamp in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` Only Gists updated at or after this time are returned. 383 | 384 | Often a resource query parameter is specific to just one of the resource actions. In this case you can discuss it in the relevant action only. No matter where you discuss a query parameter it follows exactly the same syntax as with [URI Parameters][]. 385 | 386 | ## Subsequent Resource 387 | The last missing piece in the expected functionality is the Star Resource and its actions. Utilizing everything we have learned so far the Star Resource and its actions are defined as follows: 388 | 389 | ## Star [/gists/{id}/star] 390 | Star resource represents a Gist starred status. 391 | 392 | The Star resource has the following attribute: 393 | 394 | - starred 395 | 396 | 397 | + Parameters 398 | 399 | + id (string) ... ID of the gist in the form of a hash 400 | 401 | + Model (application/hal+json) 402 | 403 | HAL+JSON representation of Star Resource. 404 | 405 | + Headers 406 | 407 | Link: ;rel="self" 408 | 409 | + Body 410 | 411 | { 412 | "_links": { 413 | "self": { "href": "/gists/42/star" }, 414 | }, 415 | "starred": true 416 | } 417 | 418 | ### Star a Gist [PUT] 419 | + Response 204 420 | 421 | ### Unstar a Gist [DELETE] 422 | + Response 204 423 | 424 | ### Check if a Gist is Starred [GET] 425 | + Response 200 426 | 427 | [Star][] 428 | 429 | ## Complete Blueprint 430 | You can find the complete Gist Fox API blueprint [full listing][] in the [API Blueprint Examples][] repository. 431 | 432 | ## API Blueprint Tools 433 | With Gist Fox Blueprint completed it is time to put it at work. For the start you can browse this API [rendered by GitHub][] or enjoy it [rendered by Apiary][]. 434 | 435 | Visit the [Tooling Section][] of the [apiblueprint.org][] to find more about tools you can use with your blueprint. 436 | 437 | --- 438 | 439 | 440 | ### Note on Indentation 441 | In API Blueprint payload assets are represented by [Markdown pre-formatted code blocks][]. This means **an asset has to be indented by four spaces** relative to its existing indentation level. In the case of Markdown list items, which are also (by definition) indented, it is even one more level further making it a total of **eight spaces** or whopping twelve spaces for list items nested under another list item. 442 | 443 | For example, the asset in `Body` list item which is nested under the `Response 200` item is indented by twelve spaces. 444 | 445 | You can save one level of indentation using the [GitHub-flavored Markdown][] syntax for [fenced code blocks][]: 446 | 447 | + Response 200 (application/hal+json) 448 | + Headers 449 | 450 | ``` 451 | Link: ;rel="self",;rel="gists" 452 | ``` 453 | + Body 454 | 455 | ``` 456 | { 457 | "_links": { 458 | "self": { "href": "/" }, 459 | "gists": { "href": "/gists?{since}", "templated": true } 460 | } 461 | } 462 | ``` 463 | 464 | [GitHub Gists]: https://gist.github.com 465 | [API Blueprint Glossary of Terms]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md 466 | [Markdown Tutorial]: http://www.markdowntutorial.com 467 | [Gruber's Original]: http://daringfireball.net/projects/markdown/syntax 468 | [API Blueprint Identifier]: https://github.com/apiaryio/api-blueprint/blob/1A/API%20Blueprint%20Specification.md#Identifiers 469 | [HTTP Request Method]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md 470 | [status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md 471 | [message-headers]: https://github.com/for-GET/know-your-http-well/blob/master/headers.md 472 | [payload]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload 473 | [`application/hal+json`]: https://github.com/mikekelly/hal_specification 474 | [Note on Indentation]: #indentation 475 | [URI Template]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#uri-template 476 | [Resource Parameters Section]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#ResourceParametersSection 477 | [Markdown pre-formatted code blocks]: http://daringfireball.net/projects/markdown/syntax#precode 478 | [GitHub-flavored Markdown]: https://help.github.com/articles/github-flavored-markdown 479 | [fenced code blocks]:https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks 480 | [URI Parameters]: #uri-parameters 481 | [API Blueprint Examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples 482 | [full listing]: https://raw.github.com/apiaryio/api-blueprint/master/examples/Gist%20Fox%20API.md 483 | [rendered by GitHub]: https://github.com/apiaryio/api-blueprint/blob/master/examples/Gist%20Fox%20API.md 484 | [rendered by Apiary]: http://docs.gistfoxapi.apiary.io 485 | [Tooling Section]: http://apiblueprint.org/#tooling 486 | [apiblueprint.org]: http://apiblueprint.org 487 | [specification]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md 488 | [map]: https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map 489 | -------------------------------------------------------------------------------- /API Blueprint Specification.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | Author: z@apiary.io 4 | Version: 1A5 5 | 6 | --- 7 | 8 | # API Blueprint 9 | #### Format 1A revision 5 10 | 11 | ## [I. API Blueprint Language](#def-api-blueprint-language) 12 | 1. [Introduction](#def-introduction) 13 | 2. [API Blueprint](#def-api-blueprint) 14 | 3. [API Blueprint document](#def-api-blueprint-document) 15 | 4. [Blueprint section](#def-blueprint-section) 16 | 1. [Section types](#def-section-types) 17 | 2. [Section structure](#def-section-structure) 18 | 3. [Keywords](#def-keywords) 19 | 4. [Identifier](#def-identifier) 20 | 5. [Description](#def-description) 21 | 6. [Nested sections](#def-nested-sections) 22 | 23 | ## [II. Sections Reference](#def-sections-reference) 24 | 1. [Named section](#def-named-section) 25 | 2. [Asset section](#def-asset-section) 26 | 3. [Payload section](#def-payload-section) 27 | 4. [Headers section](#def-headers-section) 28 | 5. [Body section](#def-body-section) 29 | 6. [Schema section](#def-schema-section) 30 | 7. [Metadata section](#def-metadata-section) 31 | 8. [API name & overview section](#def-api-name-section) 32 | 9. [Resource group section](#def-resourcegroup-section) 33 | 10. [Resource section](#def-resource-section) 34 | 11. [Resource model section](#def-model-section) 35 | 12. [URI parameters section](#def-uriparameters-section) 36 | 13. [Action section](#def-action-section) 37 | 14. [Request section](#def-request-section) 38 | 15. [Response section](#def-response-section) 39 | 40 | --- 41 | 42 |
43 | 44 | 45 | # I. API Blueprint Language 46 | 47 | 48 | ## 1. Introduction 49 | This documents is full specification of the API Blueprint format. For a less formal introduction to API Blueprint visit the [API Blueprint Tutorial](Tutorial.md) or check some of the [examples](examples). 50 | 51 | 52 | ## 2. API Blueprint 53 | API Blueprint is documentation-oriented web API description language. The API Blueprint is essentially a set of semantical assumptions laid on top of the Markdown syntax used to describe a web API. 54 | 55 | In addition to the regular [Markdown syntax][] API Blueprint conforms to the [GitHub Flavored Markdown syntax][]. 56 | 57 | 58 | ## 3. API Blueprint document 59 | An API Blueprint document – a blueprint is a plain text Markdown document describing a Web API or its part. The document is structured into logical **sections**. Each section has its distinctive meaning, content and position in the document. 60 | 61 | General section definition and structure is discussed in detail later in the [Blueprint section](#document-sections) chapter. 62 | 63 | All of the blueprint sections are optional. However, when present, a section **must** follow the API Blueprint **document structure**. 64 | 65 | ### Blueprint document structure 66 | 67 | + [`0-1` **Metadata** section](#def-metadata-section) 68 | + [`0-1` **API Name & overview** section](#def-api-name-section) 69 | + [`0+` **Resource** sections](#def-resource-section) 70 | + [`0-1` **URI Parameters** section](#def-uriparameters-section) 71 | + [`0-1` **Model** section](#def-model-section) 72 | + [`0-1` **Headers** section](#def-headers-section) 73 | + [`0-1` **Body** section](#def-body-section) 74 | + [`0-1` **Schema** section](#def-schema-section) 75 | + [`1+` **Action** sections](#def-action-section) 76 | + [`0-1` **URI Parameters** section](#def-uriparameters-section) 77 | + [`0+` **Request** sections](#def-request-section) 78 | + [`0-1` **Headers** section](#def-headers-section) 79 | + [`0-1` **Body** section](#def-body-section) 80 | + [`0-1` **Schema** section](#def-schema-section) 81 | + [`1+` **Response** sections](#def-response-section) 82 | + [`0-1` **Headers** section](#def-headers-section) 83 | + [`0-1` **Body** section](#def-body-section) 84 | + [`0-1` **Schema** section](#def-schema-section) 85 | + [`0+` **Resource Group** sections](#def-resourcegroup-section) 86 | + [`0+` **Resource** sections](#def-resource-section) (see above) 87 | 88 | > **NOTE:** The number prior to a section name denotes the allowed number of the section occurrences. 89 | 90 | > **NOTE:** Refer to [Sections Reference](#def-sections-reference) for description of a specific section type. 91 | 92 | 93 | ## 4. Blueprint section 94 | Section represents a logical unit of API Blueprint. For example an API overview, a group of resources or a resource definition. 95 | 96 | In general a section is **defined** using a **keyword** in a Markdown entity. 97 | Depending on the type of section the keyword is written either as a Markdown header entity or in a list item entity. 98 | 99 | A section definition **may** also contain additional variable components such as its **identifier** and additional modifiers. 100 | 101 | > **NOTE**: There are two special sections that are recognized by their position in the document instead of a keyword: The [Metadata section]() and the [API Name & Overview section](). Refer to the respective section entry for details on its definition. 102 | 103 | #### Example: Header-defined sections 104 | 105 | # 106 | 107 | ... 108 | 109 | # 110 | 111 | ... 112 | 113 | 114 | > **NOTE:** While this specification uses "atx" -style headers (using `#`s) 115 | > you can also use "Setext" [header syntax][] interchangably: 116 | > 117 | > 118 | > ========= 119 | > 120 | > ... 121 | > 122 | > 123 | > ========= 124 | > 125 | > ... 126 | 127 | #### Example: List-defined sections 128 | 129 | + 130 | 131 | ... 132 | 133 | + 134 | 135 | ... 136 | 137 | > **NOTE:** While this specification uses pluses (`+`) as list markers you can use any Markdown [list syntax][] using asterisks (`*`), pluses (`+`) and hyphens (`-`) interchangably: 138 | > 139 | > * 140 | > 141 | > ... 142 | > 143 | > - 144 | > 145 | > ... 146 | 147 | 148 | ### 4.1 Section types 149 | There are several types of API Blueprint sections. You can find the complete listing of the section types in the [Section Reference](#def-sections-reference). 150 | 151 | **The Blueprint section chapter discusses the section syntax in general. A specific section type may conform only to some parts of this general syntax.** Always refer for respective section reference for details on its syntax. 152 | 153 | 154 | ### 4.2 Section structure 155 | A general structure of an API Blueprint section defined by a **keyword** includes an **identifier** (name), section **description** and **nested sections** or a specifically formatted content. 156 | 157 | #### Example: Header-defined section structure 158 | 159 | # 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | #### Example: List-defined section structure 168 | 169 | + 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | ### 4.3 Keywords 179 | Following reserved keywords are used in section definitions: 180 | 181 | #### Header keywords 182 | - `Group` 183 | - [HTTP methods][httpmethods] (e.g. `GET, POST, PUT, DELETE`...) 184 | - [URI templates][uritemplate] (e.g. `/resource/{id}`) 185 | - Combinations of an HTTP method and URI Template (e.g. `GET /resource/{id}`) 186 | 187 | #### List keywords 188 | - `Request` 189 | - `Response` 190 | - `Body` 191 | - `Schema` 192 | - `Model` 193 | - `Header` & `Headers` 194 | - `Parameter` & `Parameters` 195 | - `Values` 196 | 197 | > **NOTE: Avoid using these keywords in other Markdown headers or lists** 198 | 199 | > **NOTE:** With the exception of HTTP methods keywords the section keywords are case insensitive. 200 | 201 | 202 | ### 4.4 Identifier 203 | A section definition **may** or **must** include an identifier of the section. An **identifier is any non-empty combination of any character except `[`, `]`, `(`, `)` and newline characters**. 204 | 205 | An identifier **must not** contain any of the [keywords](#def-keywords). 206 | 207 | #### Example 208 | 209 | ``` 210 | Adam's Message 42 211 | ``` 212 | 213 | ``` 214 | my-awesome-message_2 215 | ``` 216 | 217 | 218 | 219 | ### 4.5 Description 220 | A section description is any arbitrary Markdown-formatted content following the section definition. 221 | 222 | It is possible to use any Markdown header or list item in a section description as long as it does not clash with any of the [reserved keywords](#def-keywords). 223 | 224 | > **NOTE:** It is considered good practice to keep the header level nested under the actual section. 225 | 226 | 227 | ### 4.6 Nested sections 228 | A section **may** contain another nested section(s). 229 | 230 | Depending on the nested section type, to nest a section simply increase its header level or its list item indentation. Anything between the section start and the start of following section at the same level is considered to be part of the section. 231 | 232 | What sections can be nested an where depends upon the section in case, as described in the relevant section's entry. 233 | 234 | #### Example: Nested header-defined section 235 | 236 | #
237 | 238 | ... 239 | 240 | ## 241 | 242 | ... 243 | 244 | #### Example: Nested list-defined section 245 | 246 | +
247 | 248 | ... 249 | 250 | + 251 | 252 | ... 253 | 254 | > **NOTE:** While not necessary it is a good habit to increase the level of a nested section markdown-header. 255 | 256 | > **NOTE:** A markdown-list section is always considered to be nested under the preceding markdown-header section. 257 | 258 | --- 259 | 260 | 261 | # II. Sections Reference 262 | > **NOTE:** Sections marked as "Abstract" serve as a base for other sections and as such they **cannot** be used directly. 263 | 264 | 265 | ## 1. Named section 266 | - **Abstract** 267 | - **Parent sections:** vary, see descendants 268 | - **Nested sections:** vary, see descendants 269 | - **Markdown entity:** header, list 270 | - **Inherits from**: none 271 | 272 | #### Definition 273 | Defined by a [keyword](#def-keywords) followed by an optional section name - [identifier](#def-identifier) in a Markdown header or list entity. 274 | 275 | ``` 276 | # 277 | ``` 278 | 279 | ``` 280 | + 281 | ``` 282 | 283 | #### Description 284 | Named section is the base section for most of the API Blueprint sections. It conforms to the [general section](#def-section-structure) and as such it composes of a section name (identifier), description and nested sections or specific formatted content (see descendants descriptions). 285 | 286 | #### Example 287 | 288 | # Section Name 289 | This the `Section Name` description. 290 | 291 | - one 292 | - **two** 293 | - three 294 | 295 | | 296 | 297 | --- 298 | 299 | 300 | ## 2. Asset section 301 | - **Abstract** 302 | - **Parent sections:** vary, see descendants 303 | - **Nested sections:** none 304 | - **Markdown entity:** list 305 | - **Inherits from**: none 306 | 307 | #### Definition 308 | Defined by a [keyword](#def-keywords) in Markdown list entity. 309 | 310 | + 311 | 312 | #### Description 313 | Asset section is the base section for atomic data in API Blueprint. The content this section is expected to be a [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode). 314 | 315 | #### Example 316 | 317 | + 318 | 319 | { 320 | "message": "Hello" 321 | } 322 | 323 | #### Example: Fenced code blocks 324 | 325 | + 326 | 327 | ``` 328 | { 329 | "message": "Hello" 330 | } 331 | ``` 332 | 333 | --- 334 | 335 | 336 | ## 3. Payload section 337 | - **Abstract** 338 | - **Parent sections:** vary, see descendants 339 | - **Nested sections:** [`0-1` Headers section](#def-headers-section), [`0-1` Body section](#def-body-section), [`0-1` Schema section](#def-schema-section) 340 | - **Markdown entity:** list 341 | - **Inherits from**: [Named section](#def-named-section) 342 | 343 | #### Definition 344 | Defined by a [keyword](#def-keywords) in Markdown list entity. The keyword **may** be followed by identifier. The definition **may** include payload's media-type enclosed in braces. 345 | 346 | + () 347 | 348 | > **NOTE:** Refer to descendant for the particular section type definition. 349 | 350 | #### Description 351 | Payload sections represent the information transferred as a payload of an HTTP request or response messages. A Payload consists of optional meta information in the form of HTTP headers and optional content in the form HTTP body. 352 | 353 | Furthermore, in API Blueprint context, a payload include a description and a validation schema. 354 | 355 | A payload section **may** have its media type associated. A payload's media type represents the metadata received or sent in the form of a HTTP `Content-Type` header. When specified a payload **should** include nested [Body section](#def-body-section). 356 | 357 | This section **should** include at least one following nested sections: 358 | 359 | - [`0-1` Headers section](#def-headers-section) 360 | - [`0-1` Body section](#def-body-section) 361 | - [`0-1` Schema section](#def-schema-section) 362 | 363 | If there is no nested section the content of the payload section is considered as content of the [Body section](#def-body-section). 364 | 365 | #### Referencing 366 | Instead of providing a payload section content a previously defined [model payload section](#def-model-section) can be referenced using the Markdown implicit [reference syntax][]: 367 | 368 | [][] 369 | 370 | #### Example 371 | 372 | + Payload Name (application/json) 373 | 374 | This the `Payload Name` description. 375 | 376 | + Headers 377 | 378 | ... 379 | 380 | + Body 381 | 382 | ... 383 | 384 | + Schema 385 | 386 | ... 387 | 388 | #### Example: Referencing model payload 389 | 390 | + Payload Name 391 | 392 | [Resource model identifier][] 393 | 394 | --- 395 | 396 | 397 | ## 4. Headers section 398 | - **Parent sections:** [Payload section](#def-payload-section) 399 | - **Nested sections:** none 400 | - **Markdown entity:** list 401 | - **Inherits from**: none 402 | 403 | #### Definition 404 | Defined by the `Headers` keyword in Markdown list entity. 405 | 406 | + Headers 407 | 408 | #### Description 409 | Specifies the HTTP message-headers of the parent payload section. The content this section is expected to be a [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode) with the following syntax: 410 | 411 | : 412 | 413 | One HTTP header per line. 414 | 415 | #### Example 416 | 417 | + Headers 418 | 419 | Accept-Charset: utf-8 420 | Connection: keep-alive 421 | Content-Type: multipart/form-data, boundary=AaB03x 422 | 423 | --- 424 | 425 | 426 | ## 5. Body section 427 | - **Parent sections:** [Payload section](#def-payload-section) 428 | - **Nested sections:** none 429 | - **Markdown entity:** list 430 | - **Inherits from**: [Asset section](#def-asset-section) 431 | 432 | #### Definition 433 | Defined by the `Body` keyword in Markdown list entity. 434 | 435 | + Body 436 | 437 | #### Description 438 | Specifies the HTTP message-body of a payload section. 439 | 440 | #### Example 441 | 442 | + Body 443 | 444 | { 445 | "message": "Hello" 446 | } 447 | 448 | --- 449 | 450 | 451 | ## 6. Schema section 452 | - **Parent sections:** [Payload section](#def-payload-section) 453 | - **Nested sections:** none 454 | - **Markdown entity:** list 455 | - **Inherits from**: [Asset section](#def-asset-section) 456 | 457 | #### Definition 458 | Defined by the `Schema` keyword in Markdown list entity. 459 | 460 | + Schema 461 | 462 | #### Description 463 | Specifies a validation schema for the HTTP message-body of parent payload section. 464 | 465 | --- 466 | 467 | 468 | ## 7. Metadata section 469 | - **Parent sections:** none 470 | - **Nested sections:** none 471 | - **Markdown entity:** special 472 | - **Inherits from**: none 473 | 474 | #### Definition 475 | Key value pairs. Key separated from its value by colon (`:`). One pair per line. 476 | Starts at the beginning of the document and ends with the first Markdown element that is not recognized as a key value pair. 477 | 478 | #### Description 479 | Metadata keys and its values are tool-specific. Refer to relevant tool documentation for the list of supported keys. 480 | 481 | #### Example 482 | 483 | HOST: http://blog.acme.com 484 | FORMAT: 1A 485 | 486 | --- 487 | 488 | 489 | ## 8. API name & overview section 490 | - **Parent sections:** none 491 | - **Nested sections:** none 492 | - **Markdown entity:** special, header 493 | - **Inherits from**: [Named section](#def-named-section) 494 | 495 | #### Definition 496 | Defined by the **first** Markdown header in the blueprint document unless it represents another section definition. 497 | 498 | #### Description 499 | Name and description of the API 500 | 501 | #### Example 502 | 503 | # Basic ACME Blog API 504 | Welcome to the **ACME Blog** API. This API provides access to the **ACME Blog** service. 505 | 506 | --- 507 | 508 | 509 | ## 9. Resource group section 510 | - **Parent sections:** none 511 | - **Nested sections:** [`0+` Resource section](#def-resource-section) 512 | - **Markdown entity:** header 513 | - **Inherits from**: [Named section](#def-named-section) 514 | 515 | #### Definition 516 | Defined by the `Group` keyword followed by group [name (identifier)](#def-identifier): 517 | 518 | # Group 519 | 520 | #### Description 521 | This sections represents a group of resources (Resource Sections). **May** include one or more nested [Resource Sections](#def-resource-section). 522 | 523 | #### Example 524 | 525 | # Group Blog Posts 526 | 527 | ## Resource 1 [/resource1] 528 | 529 | ... 530 | 531 | # Group Authors 532 | Resources in this groups are related to **ACME Blog** authors. 533 | 534 | ## Resource 2 [/resource2] 535 | 536 | ... 537 | 538 | --- 539 | 540 | 541 | ## 10. Resource section 542 | - **Parent sections:** none, [Resource group section](#def-resourcegroup-section) 543 | - **Nested sections:** [`0-1` Parameters section](#def-uriparameters-section), [`0-1` Model section](#def-model-section), [`1+` Action section](#def-action-section) 544 | - **Markdown entity:** header 545 | - **Inherits from**: [Named section](#def-named-section) 546 | 547 | #### Definition 548 | Defined by an [RFC 6570 URI template][uritemplate]: 549 | 550 | # 551 | 552 | **-- or --** 553 | 554 | Defined by a resource [name (identifier)](#def-identifier) followed by URI template enclosed in square brackets `[]`. 555 | 556 | # [] 557 | 558 | **-- or --** 559 | 560 | Defined by an [HTTP request method][httpmethods] followed by URI template: 561 | 562 | # 563 | 564 | > **NOTE:** In this case the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**. 565 | 566 | #### Description 567 | An API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by its *URI* or a set of resources (a resource template) matching its *URI template*. 568 | 569 | This section **should** include at least one nested [Action section](#def-action-section) and **may** include following nested sections: 570 | 571 | - [`0-1` Model section](#def-model-section) 572 | - [`0-1` URI parameters section](#def-uriparameters-section) 573 | - Additional [Action sections](#def-action-section) 574 | 575 | > **NOTE:** A blueprint document may contain multiple sections for the same resource (or resource set), as long as their HTTP methods differ. However it is considered good practice to group multiple HTTP methods under one resource (resource set). 576 | 577 | #### Example 578 | 579 | ``` 580 | # Blog Posts [/posts/{id}] 581 | Resource representing **ACME Blog** posts. 582 | ``` 583 | 584 | ``` 585 | # /posts/{id} 586 | ``` 587 | 588 | ``` 589 | # GET /posts/{id} 590 | ``` 591 | 592 | --- 593 | 594 | 595 | ## 11. Resource model section 596 | - **Parent sections:** [Resource section](#def-resource-section) 597 | - **Nested sections:** [Refer to payload section](#def-payload-section) 598 | - **Markdown entity:** list 599 | - **Inherits from**: [Payload section](#def-payload-section) 600 | 601 | #### Definition 602 | Defined by the `Model` keyword followed by an optional media type: 603 | 604 | + Model () 605 | 606 | #### Description 607 | A [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) - one exemplar representation of the resource in the form of a [payload](#def-payload-section). 608 | 609 | #### Referencing 610 | The payload defined in this section **may** be referenced later using parent section's identifier. You can refer to this payload in any of the following [Request](#def-request-section) or [Response](#def-response-section) payload sections using the Markdown implicit [reference syntax][]. 611 | 612 | #### Example 613 | 614 | # My Resource [/resource] 615 | + Model (text/plain) 616 | 617 | Hello World 618 | 619 | ## Retrieve My Resource [GET] 620 | + Response 200 621 | 622 | [My Resource][] 623 | 624 | 625 | --- 626 | 627 | 628 | ## 12. URI parameters section 629 | - **Parent Sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) 630 | - **Nested Sections:** none 631 | - **Markdown entity:** list 632 | - **Inherits from**: none, special 633 | 634 | #### Definition 635 | Defined by the `Parameters` keyword written in a Markdown list item: 636 | 637 | + Parameters 638 | 639 | #### Description 640 | Discussion of parent section's URI parameters. 641 | 642 | This section **must** be composed of nested list items only. This section **must not** contain any other elements. One list item per URI parameter. The nested list items subsections inherit from the [Named section](#def-named-section) and are subject to additional formatting as follows: 643 | 644 | + = `` (required | optional , , ``) ... 645 | 646 | 647 | 648 | + Values 649 | + `` 650 | + `` 651 | ... 652 | + `` 653 | 654 | Where: 655 | 656 | * `` is the parameter name as written in [Resource Section](#ResourceSection)'s URI (e.g. "id"). 657 | * `` is any **optional** Markdown-formatted description of the parameter. 658 | * `` is any additional **optional** Markdown-formatted [description](#SectionDescription) of the parameter. 659 | * `` is an **optional** default value of the parameter – a value that is used when no value is explicitly set (optional parameters only). 660 | * `` is an **optional** example value of the parameter (e.g. `1234`). 661 | * `` is the **optional** parameter type as expected by the API (e.g. "number"). 662 | * `Values` is the **optional** enumeration of possible values 663 | * and `` represents an element of enumeration type. 664 | * `required` is the **optional** specifier of a required parameter (this is the **default**) 665 | * `optional` is the **optional** specifier of an optional parameter. 666 | 667 | > **NOTE:** This section does not have to list every URI parameter. It **should not**, however, contain parameters that are not specified in the parents' URI template. 668 | 669 | #### Example 670 | 671 | ``` 672 | # GET /posts/{id} 673 | ``` 674 | 675 | ``` 676 | + Parameters 677 | + id ... Id of a post. 678 | ``` 679 | 680 | ``` 681 | + Parameters 682 | + id (number) ... Id of a post. 683 | ``` 684 | 685 | ``` 686 | + Parameters 687 | + id (required, number, `1001`) ... Id of a post. 688 | ``` 689 | 690 | ``` 691 | + Parameters 692 | + id = `20` (optional, number, `1001`) ... Id of a post. 693 | ``` 694 | 695 | ``` 696 | + Parameters 697 | + id (string) 698 | 699 | Id of a Post 700 | 701 | + Values 702 | + `A` 703 | + `B` 704 | + `C` 705 | ``` 706 | --- 707 | 708 | 709 | ## 13. Action section 710 | - **Parent sections:** [Resource section](#def-resource-section) 711 | - **Nested sections:** [`0-1` URI parameters section](#def-uriparameters-section), [`0+` Request section](#def-request-section), [`1+` Response section](#def-response-section) 712 | - **Markdown entity:** header 713 | - **Inherits from**: [Named section](#def-named-section) 714 | 715 | #### Definition 716 | Defined by an [HTTP request method][httpmethods]: 717 | 718 | ## 719 | 720 | **-- or --** 721 | 722 | Defined by an action [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] enclosed in square brackets `[]`. 723 | 724 | # [] 725 | 726 | #### Description 727 | Definition of at least one complete HTTP transaction as performed with the parent resource section. An action section **may** consists of multiple HTTP transaction examples for the given HTTP request method. 728 | 729 | This section **may** include one nested [URI parameters section](#def-uriparameters-section) describing any URI parameters _specific_ to the action. It **should** include at least one nested [Response section](#def-response-section) and **may** include additional nested [Request](#def-request-section) and [Response](#def-response-section) sections. 730 | 731 | Nested Request and Response sections **may** be ordered into groups where each groups represent one transaction example. First transaction example group starts with the first nested Request or Response section. Subsequent groups start with the first nested Request section following a Response section. 732 | 733 | Mutliple Request and Response nested sections within one transaction example **should** have different identifiers. 734 | 735 | #### Example 736 | 737 | # Blog Posts [/posts{?limit}] 738 | ... 739 | 740 | ## Retrieve Blog Posts [GET] 741 | Retrieves the list of **ACME Blog** posts. 742 | 743 | + Parameters 744 | + limit (optional, number) ... Maximum number of posts ot retrieve 745 | 746 | + Response 200 747 | 748 | ... 749 | 750 | ### Create a Post [POST] 751 | + Request 752 | 753 | ... 754 | 755 | + Response 201 756 | 757 | ... 758 | 759 | #### Example Multiple Transaction Examples 760 | 761 | # Resource [/resource] 762 | ## Create Resource [POST] 763 | 764 | + request A 765 | 766 | ... 767 | 768 | + response 200 769 | 770 | ... 771 | 772 | + request B 773 | 774 | ... 775 | 776 | + response 200 777 | 778 | ... 779 | 780 | + response 500 781 | 782 | ... 783 | 784 | + request C 785 | 786 | ... 787 | 788 | + request D 789 | 790 | ... 791 | 792 | + response 200 793 | 794 | ... 795 | 796 | > **NOTE:** The "Multiple Transaction Examples" example demonstrates three transaction examples for one given action: 797 | > 798 | > 1. 1st example: request `A`, response `200` 799 | > 2. 2nd example: request `B`, responses `200` and `500` 800 | > 3. 3rd example: requests `C` and `D`, response `200` 801 | 802 | --- 803 | 804 | 805 | ## 14. Request section 806 | - **Parent sections:** [Action section](#def-action-section) 807 | - **Nested sections:** [Refer to payload section](#def-payload-section) 808 | - **Markdown entity:** list 809 | - **Inherits from**: [Payload section](#def-payload-section) 810 | 811 | #### Definition 812 | Defined by the `Request` keyword followed by an optional [identifier](#def-identifier): 813 | 814 | + Request () 815 | 816 | #### Description 817 | One HTTP request-message example – payload. 818 | 819 | #### Example 820 | 821 | + Request Create Blog Post (application/json) 822 | 823 | { "message" : "Hello World." } 824 | 825 | --- 826 | 827 | 828 | ## 15. Response section 829 | - **Abstract** 830 | - **Parent sections:** [Action section](#def-action-section) 831 | - **Nested sections:** [Refer to payload section](#def-payload-section) 832 | - **Markdown entity:** list 833 | - **Inherits from**: [Payload section](#def-payload-section) 834 | 835 | #### Definition 836 | Defined by the `Response` keyword. The response section definition **should** include an [HTTP status code][] as its identifier. 837 | 838 | + Response () 839 | 840 | #### Description 841 | One HTTP response-message example – payload. 842 | 843 | #### Example 844 | 845 | + Response 201 (application/json) 846 | 847 | { "message" : "created" } 848 | 849 | --- 850 | 851 | [apiblueprint.org]: http://apiblueprint.org 852 | [markdown syntax]: http://daringfireball.net/projects/markdown 853 | [reference syntax]: http://daringfireball.net/projects/markdown/syntax#link 854 | [gitHub flavored markdown syntax]: https://help.github.com/articles/github-flavored-markdown 855 | [httpmethods]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md#know-your-http-methods-well 856 | [uritemplate]: http://tools.ietf.org/html/rfc6570 857 | [HTTP status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md 858 | [header syntax]: https://daringfireball.net/projects/markdown/syntax#header 859 | [list syntax]: https://daringfireball.net/projects/markdown/syntax#list 860 | --------------------------------------------------------------------------------