├── .gitignore ├── API Blueprint Specification.md ├── Advanced Tutorial.md ├── Glossary of Terms.md ├── LICENSE ├── README.md ├── Tutorial.md ├── assets ├── lifecycle.png ├── logo_apiblueprint.png └── map.png └── examples ├── 01. Simplest API.md ├── 02. Resource and Actions.md ├── 03. Named Resource and Actions.md ├── 04. Grouping Resources.md ├── 05. Responses.md ├── 06. Requests.md ├── 07. Parameters.md ├── 08. Attributes.md ├── 09. Advanced Attributes.md ├── 10. Data Structures.md ├── 11. Resource Model.md ├── 12. Advanced Action.md ├── 13. Named Endpoints.md ├── 14. JSON Schema.md ├── 15. Advanced JSON Schema.md ├── Gist Fox API + Auth.md ├── Gist Fox API.md ├── Polls API.md ├── Polls Hypermedia API.md ├── README.md └── Real World API.md /.gitignore: -------------------------------------------------------------------------------- 1 | _site 2 | node_modules 3 | .DS_Store 4 | npm-debug.log -------------------------------------------------------------------------------- /API Blueprint Specification.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | Author: z@apiary.io 4 | Version: 1A9 5 | 6 | --- 7 | 8 | # API Blueprint 9 | #### Format 1A revision 9 10 | 11 | ## [I. API Blueprint Language](#def-api-blueprint-language) 12 | + [Introduction](#def-introduction) 13 | + [API Blueprint](#def-api-blueprint) 14 | + [API Blueprint document](#def-api-blueprint-document) 15 | + [Blueprint section](#def-blueprint-section) 16 | + [Section types](#def-section-types) 17 | + [Section structure](#def-section-structure) 18 | + [Keywords](#def-keywords) 19 | + [Identifier](#def-identifier) 20 | + [Description](#def-description) 21 | + [Nested sections](#def-nested-sections) 22 | 23 | ## [II. Sections Reference](#def-sections-reference) 24 | 25 | ### Abstract 26 | + [Named section](#def-named-section) 27 | + [Asset section](#def-asset-section) 28 | + [Payload section](#def-payload-section) 29 | 30 | ### Section Basics 31 | + [Metadata section](#def-metadata-section) 32 | + [API name & overview section](#def-api-name-section) 33 | + [Resource group section](#def-resourcegroup-section) 34 | + [Resource section](#def-resource-section) 35 | + [Resource model section](#def-model-section) 36 | + [Schema section](#def-schema-section) 37 | + [Action section](#def-action-section) 38 | + [Request section](#def-request-section) 39 | + [Response section](#def-response-section) 40 | + [URI parameters section](#def-uriparameters-section) 41 | + [Attributes section](#def-attributes-section) 42 | + [Headers section](#def-headers-section) 43 | + [Body section](#def-body-section) 44 | 45 | ### Going Further 46 | + [Data Structures section](#def-data-structures) 47 | + [Relation section](#def-relation-section) 48 | 49 | 50 | ## [III. Appendix](#def-appendix) 51 | + [URI Templates](#def-uri-templates) 52 | 53 | --- 54 | 55 |
56 | 57 | 58 | # I. API Blueprint Language 59 | 60 | 61 | ## Introduction 62 | This documents is a full specification of the API Blueprint format. For a less 63 | formal introduction to API Blueprint visit the 64 | [API Blueprint Tutorial](Tutorial.md) or check some of the [examples][]. 65 | 66 | 67 | ## API Blueprint 68 | API Blueprint is a documentation-oriented web API description language. The 69 | API Blueprint is essentially a set of semantic assumptions laid on top of the 70 | Markdown syntax used to describe a web API. 71 | 72 | In addition to the regular [Markdown syntax][], API Blueprint conforms to the 73 | [GitHub Flavored Markdown syntax][]. 74 | 75 | 76 | ## API Blueprint document 77 | An API Blueprint document – a blueprint – is a plain text Markdown document 78 | describing a Web API in whole or in part. The document is structured into 79 | logical **sections**. Each section has its distinctive meaning, content and 80 | position in the document. 81 | 82 | General section definition and structure is discussed in detail later in the 83 | [Blueprint section](#def-blueprint-section) chapter. 84 | 85 | All of the blueprint sections are optional. However, when present, a section 86 | **must** follow the API Blueprint **document structure**. 87 | 88 | ### Blueprint document structure 89 | 90 | + [`0-1` **Metadata** section](#def-metadata-section) 91 | + [`0-1` **API Name & overview** section](#def-api-name-section) 92 | + [`0+` **Resource** sections](#def-resource-section) 93 | + [`0-1` **URI Parameters** section](#def-uriparameters-section) 94 | + [`0-1` **Attributes** section](#def-attributes-section) 95 | + [`0-1` **Model** section](#def-model-section) 96 | + [`0-1` **Headers** section](#def-headers-section) 97 | + [`0-1` **Attributes** section](#def-attributes-section) 98 | + [`0-1` **Body** section](#def-body-section) 99 | + [`0-1` **Schema** section](#def-schema-section) 100 | + [`1+` **Action** sections](#def-action-section) 101 | + [`0-1` **Relation** section](#def-relation-section) 102 | + [`0-1` **URI Parameters** section](#def-uriparameters-section) 103 | + [`0-1` **Attributes** section](#def-attributes-section) 104 | + [`0+` **Request** sections](#def-request-section) 105 | + [`0-1` **Headers** section](#def-headers-section) 106 | + [`0-1` **Attributes** section](#def-attributes-section) 107 | + [`0-1` **Body** section](#def-body-section) 108 | + [`0-1` **Schema** section](#def-schema-section) 109 | + [`1+` **Response** sections](#def-response-section) 110 | + [`0-1` **Headers** section](#def-headers-section) 111 | + [`0-1` **Attributes** section](#def-attributes-section) 112 | + [`0-1` **Body** section](#def-body-section) 113 | + [`0-1` **Schema** section](#def-schema-section) 114 | + [`0+` **Resource Group** sections](#def-resourcegroup-section) 115 | + [`0+` **Resource** sections](#def-resource-section) (see above) 116 | + [`0+` **Data Structures** section](#def-data-structures) 117 | 118 | > **NOTE:** The number prior to a section name denotes the allowed number of 119 | > the section occurrences. 120 | 121 | > **NOTE:** Refer to [Sections Reference](#def-sections-reference) for 122 | > description of a specific section type. 123 | 124 | 125 | ## Blueprint section 126 | A _Section_ represents a logical unit of an API Blueprint. For example: an API 127 | overview, a group of resources or a resource definition. 128 | 129 | In general a section is **defined** using a **keyword** in a Markdown entity. 130 | Depending on the type of section the keyword is written either as a Markdown 131 | header entity or in a list item entity. 132 | 133 | A section definition **may** also contain additional variable components such 134 | as its **identifier** and additional modifiers. 135 | 136 | > **NOTE**: There are two special sections that are recognized by their 137 | > position in the document instead of a keyword: The [Metadata section](#def-metadata-section) and 138 | > the [API Name & Overview section](#def-api-name-section). Refer to the respective section entry 139 | > for details on its definition. 140 | 141 | #### Example: Header-defined sections 142 | 143 | # 144 | 145 | ... 146 | 147 | # 148 | 149 | ... 150 | 151 | 152 | > **NOTE:** While this specification uses "atx"-style headers (using `#`s) 153 | > you can also use "Setext" [header syntax][] interchangeably: 154 | > 155 | > 156 | > ========= 157 | > 158 | > ... 159 | > 160 | > 161 | > ========= 162 | > 163 | > ... 164 | 165 | #### Example: List-defined sections 166 | 167 | + 168 | 169 | ... 170 | 171 | + 172 | 173 | ... 174 | 175 | > **NOTE:** While this specification uses pluses (`+`) as list markers you can 176 | > use any Markdown [list syntax][] using asterisks (`*`), pluses (`+`) and 177 | > hyphens (`-`) interchangeably: 178 | > 179 | > * 180 | > 181 | > ... 182 | > 183 | > - 184 | > 185 | > ... 186 | 187 | 188 | ### Section types 189 | There are several types of API Blueprint sections. You can find the complete 190 | listing of the section types in the 191 | [Section Reference](#def-sections-reference). 192 | 193 | **The Blueprint section chapter discusses the section syntax in general.** 194 | **A specific section type may conform only to some parts of this general syntax.** 195 | Always refer for respective section reference for details on its syntax. 196 | 197 | 198 | ### Section structure 199 | A general structure of an API Blueprint section defined by a **keyword** 200 | includes an **identifier** (name), section **description** and **nested 201 | sections** or a specifically formatted content. 202 | 203 | #### Example: Header-defined section structure 204 | 205 | # 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | #### Example: List-defined section structure 214 | 215 | + 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | ### Keywords 225 | Following reserved keywords are used in section definitions: 226 | 227 | #### Header keywords 228 | - `Group` 229 | - `Data Structures` 230 | - [HTTP methods][httpmethods] (e.g. `GET, POST, PUT, DELETE`...) 231 | - [URI templates][uritemplate] (e.g. `/resource/{id}`) 232 | - Combinations of an HTTP method and URI Template (e.g. `GET /resource/{id}`) 233 | 234 | #### List keywords 235 | - `Request` 236 | - `Response` 237 | - `Body` 238 | - `Schema` 239 | - `Model` 240 | - `Header` & `Headers` 241 | - `Parameter` & `Parameters` 242 | - `Values` 243 | - `Attribute` & `Attributes` 244 | - `Relation` 245 | 246 | > **NOTE: Avoid using these keywords in other Markdown headers or lists** 247 | 248 | > **NOTE:** With the exception of HTTP methods keywords the section keywords 249 | > are case insensitive. 250 | 251 | 252 | ### Identifier 253 | A section definition **may** or **must** include an identifier of the section. 254 | An **identifier is any non-empty combination of any character except `[`, `]`, 255 | `(`, `)` and newline characters**. 256 | 257 | An identifier **must not** contain any of the [keywords](#def-keywords). 258 | 259 | #### Example 260 | 261 | ``` 262 | Adam's Message 42 263 | ``` 264 | 265 | ``` 266 | my-awesome-message_2 267 | ``` 268 | 269 | 270 | 271 | ### Description 272 | A section description is any arbitrary Markdown-formatted content following the 273 | section definition. 274 | 275 | It is possible to use any Markdown header or list item in a section description 276 | as long as it does not clash with any of the 277 | [reserved keywords](#def-keywords). 278 | 279 | > **NOTE:** It is considered good practice to keep the header level nested 280 | > under the actual section. 281 | 282 | 283 | ### Nested sections 284 | A section **may** contain another nested section(s). 285 | 286 | Depending on the nested section type, to nest a section simply increase its 287 | header level or its list item indentation. Anything between the section start 288 | and the start of following section at the same level is considered to be part 289 | of the section. 290 | 291 | Which sections can be nested and where depends upon the section in case, as 292 | described in the relevant section's entry. 293 | 294 | #### Example: Nested header-defined section 295 | 296 | #
297 | 298 | ... 299 | 300 | ## 301 | 302 | ... 303 | 304 | #### Example: Nested list-defined section 305 | 306 | +
307 | 308 | ... 309 | 310 | + 311 | 312 | ... 313 | 314 | > **NOTE:** While not necessary it is a good habit to increase the level of a 315 | > nested section markdown-header. 316 | 317 | > **NOTE:** A markdown-list section is always considered to be nested under the 318 | > preceding markdown-header section. 319 | 320 | --- 321 | 322 | 323 | # II. Sections Reference 324 | > **NOTE:** Sections marked as "Abstract" serve as a base for other sections 325 | > and as such they **cannot** be used directly. 326 | 327 | 328 | # Abstract 329 | 330 | 331 | ## Named section 332 | - **Abstract** 333 | - **Parent sections:** vary, see descendants 334 | - **Nested sections:** vary, see descendants 335 | - **Markdown entity:** header, list 336 | - **Inherits from**: none 337 | 338 | #### Definition 339 | Defined by a [keyword](#def-keywords) followed by an optional section name - 340 | [identifier](#def-identifier) in a Markdown header or list entity. 341 | 342 | ``` 343 | # 344 | ``` 345 | 346 | ``` 347 | + 348 | ``` 349 | 350 | #### Description 351 | Named section is the base section for most of the API Blueprint sections. It 352 | conforms to the [general section](#def-section-structure) and as such it is 353 | composed of a section name (identifier), description and nested sections or 354 | specific formatted content (see descendants descriptions). 355 | 356 | #### Example 357 | 358 | # Section Name 359 | This the `Section Name` description. 360 | 361 | - one 362 | - **two** 363 | - three 364 | 365 | | 366 | 367 | --- 368 | 369 | 370 | ## Asset section 371 | - **Abstract** 372 | - **Parent sections:** vary, see descendants 373 | - **Nested sections:** none 374 | - **Markdown entity:** list 375 | - **Inherits from**: none 376 | 377 | #### Definition 378 | Defined by a [keyword](#def-keywords) in Markdown list entity. 379 | 380 | + 381 | 382 | #### Description 383 | The asset section is the base section for atomic data in API Blueprint. The content 384 | of this section is expected to be a 385 | [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode). 386 | 387 | #### Example 388 | 389 | + 390 | 391 | { 392 | "message": "Hello" 393 | } 394 | 395 | #### Example: Fenced code blocks 396 | 397 | + 398 | 399 | ``` 400 | { 401 | "message": "Hello" 402 | } 403 | ``` 404 | 405 | --- 406 | 407 | 408 | ## Payload section 409 | - **Abstract** 410 | - **Parent sections:** vary, see descendants 411 | - **Nested sections:** [`0-1` Headers section](#def-headers-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Body section](#def-body-section), [`0-1` Schema section](#def-schema-section) 412 | - **Markdown entity:** list 413 | - **Inherits from**: [Named section](#def-named-section) 414 | 415 | #### Definition 416 | Defined by a [keyword](#def-keywords) in Markdown list entity. The keyword **may** be followed by identifier. 417 | The definition **may** include payload's media-type enclosed in braces. 418 | 419 | + () 420 | 421 | > **NOTE:** Refer to descendant for the particular section type definition. 422 | 423 | #### Description 424 | Payload sections represent the information transferred as a payload of an HTTP 425 | request or response messages. A Payload consists of optional meta information 426 | in the form of HTTP headers and optional content in the form of an HTTP body. 427 | 428 | Furthermore, in API Blueprint context, a payload includes its description, 429 | description of its message-body attributes and a message-body validation 430 | schema. 431 | 432 | A payload **may** have its media type associated. A payload's media type 433 | represents the metadata received or sent in the form of a HTTP `Content-Type` 434 | header. When specified a payload **should** include nested 435 | [Body section](#def-body-section). 436 | 437 | This section **should** include at least one of the following nested sections: 438 | 439 | - [`0-1` Headers section](#def-headers-section) 440 | - [`0-1` Attributes section](#def-attributes-section) 441 | - [`0-1` Body section](#def-body-section) 442 | - [`0-1` Schema section](#def-schema-section) 443 | 444 | If there is no nested section the content of the payload section is considered 445 | as content of the [Body section](#def-body-section). 446 | 447 | #### Relation of Body, Schema and Attributes sections 448 | Each of body, schema and attributes sections describe a message payload's body. 449 | These descriptions **should** be consistent, not violating each other. When 450 | multiple body descriptions are provided they **should** be prioritized as 451 | follows: 452 | 453 | 1. For resolving message-body schema 454 | 1. Schema section 455 | 2. Attributes section 456 | 3. Body section 457 | 458 | 2. For resolving message-body example 459 | 1. Body section 460 | 2. Attributes section 461 | 3. Schema section 462 | 463 | #### Referencing 464 | Instead of providing a payload section content, a 465 | [model payload section](#def-model-section) can be referenced using the 466 | Markdown implicit [reference syntax][]: 467 | 468 | [][] 469 | 470 | #### Example 471 | 472 | + Payload Name (application/json) 473 | 474 | This the `Payload Name` description. 475 | 476 | + Headers 477 | 478 | ... 479 | 480 | + Body 481 | 482 | ... 483 | 484 | + Schema 485 | 486 | ... 487 | 488 | #### Example: Referencing model payload 489 | 490 | + Payload Name 491 | 492 | [Resource model identifier][] 493 | 494 | --- 495 | 496 | 497 | # Section Basics 498 | 499 | 500 | 501 | ## Metadata section 502 | - **Parent sections:** none 503 | - **Nested sections:** none 504 | - **Markdown entity:** special 505 | - **Inherits from**: none 506 | 507 | #### Definition 508 | Key-value pairs. Each key is separated from its value by a colon (`:`). One 509 | pair per line. Starts at the beginning of the document and ends with the first 510 | Markdown element that is not recognized as a key-value pair. 511 | 512 | #### Description 513 | Metadata keys and their values are tool-specific. Refer to relevant tool 514 | documentation for the list of supported keys. 515 | 516 | #### Example 517 | 518 | FORMAT: 1A 519 | HOST: http://blog.acme.com 520 | 521 | --- 522 | 523 | 524 | ## API name & overview section 525 | - **Parent sections:** none 526 | - **Nested sections:** none 527 | - **Markdown entity:** special, header 528 | - **Inherits from**: [Named section](#def-named-section) 529 | 530 | #### Definition 531 | Defined by the **first** Markdown header in the blueprint document, unless it 532 | represents another section definition. 533 | 534 | #### Description 535 | Name and description of the API 536 | 537 | #### Example 538 | 539 | # Basic ACME Blog API 540 | Welcome to the **ACME Blog** API. This API provides access to the **ACME 541 | Blog** service. 542 | 543 | --- 544 | 545 | 546 | ## Resource group section 547 | - **Parent sections:** none 548 | - **Nested sections:** [`0+` Resource section](#def-resource-section) 549 | - **Markdown entity:** header 550 | - **Inherits from**: [Named section](#def-named-section) 551 | 552 | #### Definition 553 | Defined by the `Group` keyword followed by group [name (identifier)](#def-identifier): 554 | 555 | # Group 556 | 557 | #### Description 558 | This section represents a group of resources (Resource Sections). **May** 559 | include one or more nested [Resource Sections](#def-resource-section). 560 | 561 | #### Example 562 | 563 | ```apib 564 | # Group Blog Posts 565 | 566 | ## Resource 1 [/resource1] 567 | 568 | ... 569 | 570 | # Group Authors 571 | Resources in this groups are related to **ACME Blog** authors. 572 | 573 | ## Resource 2 [/resource2] 574 | 575 | ... 576 | ``` 577 | 578 | --- 579 | 580 | 581 | ## Resource section 582 | - **Parent sections:** none, [Resource group section](#def-resourcegroup-section) 583 | - **Nested sections:** [`0-1` Parameters section](#def-uriparameters-section), [`0-1` Attributes section](#def-attributes-section), [`0-1` Model section](#def-model-section), [`1+` Action section](#def-action-section) 584 | - **Markdown entity:** header 585 | - **Inherits from**: [Named section](#def-named-section) 586 | 587 | #### Definition 588 | Defined by an [URI template][uritemplate]: 589 | 590 | # 591 | 592 | **-- or --** 593 | 594 | Defined by a resource [name (identifier)](#def-identifier) followed by an 595 | [URI template][uritemplate] enclosed in square brackets `[]`. 596 | 597 | # [] 598 | 599 | **-- or --** 600 | 601 | Defined by an [HTTP request method][httpmethods] followed by [URI template][uritemplate]: 602 | 603 | # 604 | 605 | **-- or --** 606 | 607 | Defined by a resource [name (identifier)](#def-identifier) followed by an 608 | [HTTP request method][httpmethods] and an [URI template][uritemplate] enclosed 609 | in square brackets `[]`: 610 | 611 | # [ ] 612 | 613 | > **NOTE:** In the latter two cases the rest of this section represents the 614 | > [Action section](#def-action-section) including its description and nested 615 | > sections and **follows the rules of the Action section instead**. 616 | 617 | #### Description 618 | An API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by 619 | its *URI* or a set of resources (a resource template) matching its *URI 620 | template*. 621 | 622 | This section **should** include at least one nested 623 | [Action section](#def-action-section) and **may** include following nested 624 | sections: 625 | 626 | - [`0-1` URI parameters section](#def-uriparameters-section) 627 | 628 | URI parameters defined in the scope of a Resource section apply to 629 | _any and all_ nested Action sections except when an [URI template][uritemplate] has 630 | been defined for the Action. 631 | 632 | - [`0-1` Attributes section][] 633 | 634 | Attributes defined in the scope of a Resource section represent Resource 635 | attributes. If the resource is defined with a name these attributes **may** 636 | be referenced in [Attributes sections][]. 637 | 638 | - [`0-1` Model section](#def-model-section) 639 | 640 | - Additional [Action sections](#def-action-section) 641 | 642 | > **NOTE:** A blueprint document may contain multiple sections for the same 643 | > resource (or resource set), as long as their HTTP methods differ. However it 644 | > is considered good practice to group multiple HTTP methods under one resource 645 | > (resource set). 646 | 647 | #### Example 648 | 649 | ```apib 650 | # Blog Posts [/posts/{id}] 651 | Resource representing **ACME Blog** posts. 652 | ``` 653 | 654 | ```apib 655 | # /posts/{id} 656 | ``` 657 | 658 | ```apib 659 | # GET /posts/{id} 660 | ``` 661 | 662 | --- 663 | 664 | 665 | ## Resource model section 666 | - **Parent sections:** [Resource section](#def-resource-section) 667 | - **Nested sections:** [Refer to payload section](#def-payload-section) 668 | - **Markdown entity:** list 669 | - **Inherits from**: [Payload section](#def-payload-section) 670 | 671 | #### Definition 672 | Defined by the `Model` keyword followed by an optional media type: 673 | 674 | + Model () 675 | 676 | #### Description 677 | A [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) - one 678 | exemplary representation of the resource in the form of a 679 | [payload](#def-payload-section). 680 | 681 | #### Referencing 682 | The payload defined in this section **may** be referenced in any response or 683 | request section in the document using parent section's identifier. You can 684 | refer to this payload in any of the following [Request](#def-request-section) 685 | or [Response](#def-response-section) payload sections using the Markdown 686 | implicit [reference syntax][]. 687 | 688 | #### Example 689 | 690 | ```apib 691 | # My Resource [/resource] 692 | 693 | + Model (text/plain) 694 | 695 | Hello World 696 | 697 | ## Retrieve My Resource [GET] 698 | 699 | + Response 200 700 | 701 | [My Resource][] 702 | ``` 703 | 704 | --- 705 | 706 | 707 | ## Schema section 708 | - **Parent sections:** [Payload section](#def-payload-section) 709 | - **Nested sections:** none 710 | - **Markdown entity:** list 711 | - **Inherits from**: [Asset section](#def-asset-section) 712 | 713 | #### Definition 714 | Defined by the `Schema` keyword in Markdown list entity. 715 | 716 | + Schema 717 | 718 | #### Description 719 | Specifies a validation schema for the HTTP message-body of parent payload section. 720 | 721 | #### Example 722 | 723 | Following example uses [Body section](#def-body-section) to provide an example of an `application/json` payload, and [Schema section](#def-schema-section) to provide a [JSON Schema](http://json-schema.org/) describing all possible valid shapes of the payload. 724 | 725 | ```apib 726 | ## Retrieve a Message [GET] 727 | 728 | + Response 200 (application/json) 729 | + Body 730 | 731 | {"message": "Hello world!"} 732 | 733 | + Schema 734 | 735 | { 736 | "$schema": "http://json-schema.org/draft-04/schema#", 737 | "type": "object", 738 | "properties": { 739 | "message": { 740 | "type": "string" 741 | } 742 | } 743 | } 744 | ``` 745 | 746 | --- 747 | 748 | 749 | ## Action section 750 | - **Parent sections:** [Resource section](#def-resource-section) 751 | - **Nested sections:** 752 | [`0-1` Relation section](#def-relation-section), 753 | [`0-1` URI parameters section](#def-uriparameters-section), 754 | [`0-1` Attributes section](#def-attributes-section), 755 | [`0+` Request section](#def-request-section), 756 | [`1+` Response section](#def-response-section) 757 | - **Markdown entity:** header 758 | - **Inherits from**: [Named section](#def-named-section) 759 | 760 | #### Definition 761 | Defined by an [HTTP request method][httpmethods]: 762 | 763 | ## 764 | 765 | **-- or --** 766 | 767 | Defined by an action [name (identifier)](#def-identifier) followed by an 768 | [HTTP request method][httpmethods] enclosed in square brackets `[]`. 769 | 770 | ## [] 771 | 772 | **-- or --** 773 | 774 | Defined by an action [name (identifier)](#def-identifier) followed by an 775 | [HTTP request method][httpmethods] and 776 | [URI template][uritemplate] enclosed in square brackets `[]`. 777 | 778 | ## [ ] 779 | 780 | #### Description 781 | Definition of at least one complete HTTP transaction as performed with the 782 | parent resource section. An action section **may** consist of multiple HTTP 783 | transaction examples for the given HTTP request method. 784 | 785 | This section **may** include one nested 786 | [URI parameters section](#def-uriparameters-section) describing any URI 787 | parameters _specific_ to the action – URI parameters discussed in the scope of 788 | an Action section apply to the respective Action section ONLY. 789 | 790 | This section **may** include one nested [Attributes section][] defining the 791 | input (request) attributes of the section. If present, these attributes 792 | **should** be inherited in every Action's [Request section][] unless specified 793 | otherwise. 794 | 795 | Action section **should** include at least one nested 796 | [Response section](#def-response-section) and **may** include additional nested 797 | [Request](#def-request-section) and [Response](#def-response-section) sections. 798 | 799 | Nested Request and Response sections **may** be ordered into groups where each 800 | group represents one transaction example. The first transaction example group 801 | starts with the first nested Request or Response section. Subsequent groups 802 | start with the first nested Request section following a Response section. 803 | 804 | Multiple Request and Response nested sections within one transaction example 805 | **should** have different identifiers. 806 | 807 | #### Example 808 | 809 | ```apib 810 | # Blog Posts [/posts{?limit}] 811 | ... 812 | 813 | ## Retrieve Blog Posts [GET] 814 | Retrieves the list of **ACME Blog** posts. 815 | 816 | + Parameters 817 | + limit (optional, number) ... Maximum number of posts to retrieve 818 | 819 | + Response 200 820 | 821 | ... 822 | 823 | ## Create a Post [POST] 824 | 825 | + Attributes 826 | 827 | ... 828 | 829 | + Request 830 | 831 | ... 832 | 833 | + Response 201 834 | 835 | ... 836 | 837 | ## Delete a Post [DELETE /posts/{id}] 838 | 839 | + Parameters 840 | + id (string) ... Id of the post 841 | 842 | + Response 204 843 | ``` 844 | 845 | #### Example Multiple Transaction Examples 846 | 847 | ```apib 848 | # Resource [/resource] 849 | ## Create Resource [POST] 850 | 851 | + request A 852 | 853 | ... 854 | 855 | + response 200 856 | 857 | ... 858 | 859 | + request B 860 | 861 | ... 862 | 863 | + response 200 864 | 865 | ... 866 | 867 | + response 500 868 | 869 | ... 870 | 871 | + request C 872 | 873 | ... 874 | 875 | + request D 876 | 877 | ... 878 | 879 | + response 200 880 | 881 | ... 882 | ``` 883 | 884 | > **NOTE:** The "Multiple Transaction Examples" example demonstrates three 885 | > transaction examples for one given action: 886 | > 887 | > 1. 1st example: request `A`, response `200` 888 | > 2. 2nd example: request `B`, responses `200` and `500` 889 | > 3. 3rd example: requests `C` and `D`, response `200` 890 | 891 | --- 892 | 893 | 894 | ## Request section 895 | - **Parent sections:** [Action section](#def-action-section) 896 | - **Nested sections:** [Refer to payload section](#def-payload-section) 897 | - **Markdown entity:** list 898 | - **Inherits from**: [Payload section](#def-payload-section) 899 | 900 | #### Definition 901 | Defined by the `Request` keyword followed by an optional [identifier](#def-identifier): 902 | 903 | + Request () 904 | 905 | #### Description 906 | One HTTP request-message example – payload. 907 | 908 | #### Example 909 | 910 | ```apib 911 | + Request Create Blog Post (application/json) 912 | 913 | { "message" : "Hello World." } 914 | ``` 915 | 916 | --- 917 | 918 | 919 | ## Response section 920 | - **Parent sections:** [Action section](#def-action-section) 921 | - **Nested sections:** [Refer to payload section](#def-payload-section) 922 | - **Markdown entity:** list 923 | - **Inherits from**: [Payload section](#def-payload-section) 924 | 925 | #### Definition 926 | Defined by the `Response` keyword. The response section definition **should** 927 | include an [HTTP status code][] as its identifier. 928 | 929 | + Response () 930 | 931 | #### Description 932 | One HTTP response-message example – payload. 933 | 934 | #### Example 935 | 936 | ```apib 937 | + Response 201 (application/json) 938 | 939 | { "message" : "created" } 940 | ``` 941 | 942 | --- 943 | 944 | 945 | ## URI parameters section 946 | - **Parent Sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) 947 | - **Nested Sections:** none 948 | - **Markdown entity:** list 949 | - **Inherits from**: none, special 950 | 951 | #### Definition 952 | Defined by the `Parameters` keyword written in a Markdown list item: 953 | 954 | + Parameters 955 | 956 | #### Description 957 | Discussion of URI parameters _in the scope of the parent section_. 958 | 959 | This section **must** be composed of nested list items only. This section 960 | **must not** contain any other elements. Each list item describes a single URI 961 | parameter. The nested list items subsections inherit from the 962 | [Named section](#def-named-section) and are subject to additional formatting as 963 | follows: 964 | 965 | + : `` ( | enum[], required | optional) - 966 | 967 | 968 | 969 | + Default: `` 970 | 971 | + Members 972 | + `` 973 | + `` 974 | ... 975 | + `` 976 | 977 | Where: 978 | 979 | + `` is the parameter name as written in 980 | [Resource Section](#def-resource-section)'s URI (e.g. "id"). 981 | + `` is any **optional** Markdown-formatted description of the 982 | parameter. 983 | + `` is any additional **optional** Markdown-formatted 984 | [description](#def-description) of the parameter. 985 | + `` is an **optional** default value of the parameter – a value 986 | that is used when no value is explicitly set (optional parameters only). 987 | + `` is an **optional** example value of the parameter (e.g. `1234`). 988 | + `` is the **optional** parameter type as expected by the API (e.g. 989 | "number", "string", "boolean"). "string" is the **default**. 990 | + `Members` is the **optional** enumeration of possible values. 991 | `` should be surrounded by `enum[]` if this is present. 992 | For example, if enumeration values are present for a parameter whose type is 993 | `number`, then `enum[number]` should be used instead of `number` to. 994 | + `` represents an element of enumeration type. 995 | + `required` is the **optional** specifier of a required parameter 996 | (this is the **default**) 997 | + `optional` is the **optional** specifier of an optional parameter. 998 | 999 | > **NOTE:** This section **should only** contain parameters that are specified 1000 | > in the parent's resource URI template, and does not have to list every URI 1001 | > parameter. 1002 | 1003 | #### Example 1004 | 1005 | ```apib 1006 | # GET /posts/{id} 1007 | ``` 1008 | 1009 | ```apib 1010 | + Parameters 1011 | + id - Id of a post. 1012 | ``` 1013 | 1014 | ```apib 1015 | + Parameters 1016 | + id (number) - Id of a post. 1017 | ``` 1018 | 1019 | ```apib 1020 | + Parameters 1021 | + id: `1001` (number, required) - Id of a post. 1022 | ``` 1023 | 1024 | ```apib 1025 | + Parameters 1026 | + id: `1001` (number, optional) - Id of a post. 1027 | + Default: `20` 1028 | ``` 1029 | 1030 | ```apib 1031 | + Parameters 1032 | + id (enum[string]) 1033 | 1034 | Id of a Post 1035 | 1036 | + Members 1037 | + `A` 1038 | + `B` 1039 | + `C` 1040 | ``` 1041 | --- 1042 | 1043 | 1044 | ## Attributes Section 1045 | - **Parent sections:** [Resource section](#def-resource-section) | [Action section](#def-action-section) | [Payload section](#def-payload-section) 1046 | - **Nested sections:** See **[Markdown Syntax for Object Notation][MSON]** 1047 | - **Markdown entity:** list 1048 | - **Inherits from**: none 1049 | 1050 | #### Definition 1051 | Defined by the `Attributes` keyword followed by an optional 1052 | [MSON Type Definition][] enclosed in parentheses. 1053 | 1054 | + Attributes 1055 | 1056 | `` is the type definition of the data structure being 1057 | described. If the `` is not specified, an `object` base type 1058 | is assumed. See [MSON Type Definition][] for details. 1059 | 1060 | ##### Example 1061 | 1062 | ```apib 1063 | + Attributes (object) 1064 | ``` 1065 | 1066 | #### Description 1067 | This section describes a data structure using the 1068 | **[Markdown Syntax for Object Notation][MSON] (MSON)**. 1069 | Based on the parent section, the data structure being described is one of the 1070 | following: 1071 | 1072 | 1. Resource data structure attributes ([Resource section](#def-resource-section)) 1073 | 2. Action request attributes ([Action section](#def-action-section)) 1074 | 3. Payload message-body attributes ([Payload section](#def-payload-section)) 1075 | 1076 | Data structures defined in this section **may** refer to any arbitrary data 1077 | structures defined in the [Data Structures section](#def-data-structures) as 1078 | well as to any data structures defined by a named resource attributes 1079 | description (see below). 1080 | 1081 | #### Resource Attributes description 1082 | Description of the resource data structure. 1083 | 1084 | If defined in a named [Resource section](#def-resource-section), this data 1085 | structure **may** be referenced by other data structures using the resource 1086 | name. 1087 | 1088 | ##### Example 1089 | 1090 | ```apib 1091 | # Blog Post [/posts/{id}] 1092 | Resource representing **ACME Blog** posts. 1093 | 1094 | + Attributes 1095 | + id (number) 1096 | + message (string) - The blog post article 1097 | + author: john@appleseed.com (string) - Author of the blog post 1098 | ``` 1099 | 1100 | > **NOTE:** This data structure can be later referred as: 1101 | > 1102 | > + Attributes (Blog Post) 1103 | > 1104 | 1105 | #### Action Attributes description 1106 | Description of the default request message-body data structure. 1107 | 1108 | If defined, all the [Request sections](#def-request-section) of the respective 1109 | [Action section](#def-action-section) inherits these attributes unless 1110 | specified otherwise. 1111 | 1112 | ##### Example 1113 | 1114 | ```apib 1115 | ## Create a Post [POST] 1116 | 1117 | + Attributes 1118 | + message (string) - The blog post article 1119 | + author: john@appleseed.com (string) - Author of the blog post 1120 | 1121 | + Request (application/json) 1122 | 1123 | + Request (application/yaml) 1124 | 1125 | + Response 201 1126 | ``` 1127 | 1128 | #### Payload Attributes description 1129 | Description of payload (request, response, model) message-body attributes. 1130 | 1131 | Not every attribute has to be described. However, when an attribute is 1132 | described, it **should** appear in the respective 1133 | [Body section](#def-body-section) example, if a Body section is provided. 1134 | 1135 | If defined, the [Body section](#def-body-section) **may** be omitted and the 1136 | example representation **should** be generated from the attributes description. 1137 | 1138 | The description of message-body attributes **may** be used to describe 1139 | message-body validation if no [Schema section](#def-schema-section) is 1140 | provided. When a Schema section is provided, the attributes description 1141 | **should** conform to the schema. 1142 | 1143 | ##### Example 1144 | 1145 | ```apib 1146 | ## Retrieve a Post [GET] 1147 | 1148 | + Response 200 (application/json) 1149 | 1150 | + Attributes (object) 1151 | + message (string) - Message to the world 1152 | 1153 | + Body 1154 | 1155 | { "message" : "Hello World." } 1156 | ``` 1157 | 1158 | --- 1159 | 1160 | 1161 | ## Headers section 1162 | - **Parent sections:** [Payload section](#def-payload-section) 1163 | - **Nested sections:** none 1164 | - **Markdown entity:** list 1165 | - **Inherits from**: none 1166 | 1167 | #### Definition 1168 | Defined by the `Headers` keyword in Markdown list entity. 1169 | 1170 | + Headers 1171 | 1172 | #### Description 1173 | Specifies the HTTP message-headers of the parent payload section. The content 1174 | this section is expected to be a [pre-formatted code block](http://daringfireball.net/projects/markdown/syntax#precode) 1175 | with the following syntax: 1176 | 1177 | : 1178 | 1179 | One HTTP header per line. 1180 | 1181 | #### Example 1182 | 1183 | ```apib 1184 | + Headers 1185 | 1186 | Accept-Charset: utf-8 1187 | Connection: keep-alive 1188 | Content-Type: multipart/form-data, boundary=AaB03x 1189 | ``` 1190 | 1191 | --- 1192 | 1193 | 1194 | ## Body section 1195 | - **Parent sections:** [Payload section](#def-payload-section) 1196 | - **Nested sections:** none 1197 | - **Markdown entity:** list 1198 | - **Inherits from**: [Asset section](#def-asset-section) 1199 | 1200 | #### Definition 1201 | Defined by the `Body` keyword in Markdown list entity. 1202 | 1203 | + Body 1204 | 1205 | #### Description 1206 | Specifies the HTTP message-body of a payload section. 1207 | 1208 | #### Example 1209 | 1210 | ```apib 1211 | + Body 1212 | 1213 | { 1214 | "message": "Hello" 1215 | } 1216 | ``` 1217 | 1218 | --- 1219 | 1220 | 1221 | 1222 | ## Data Structures section 1223 | - **Parent sections:** none 1224 | - **Nested sections:** _MSON Named Type definition_ (see below) 1225 | - **Markdown entity:** header 1226 | - **Inherits from**: none 1227 | 1228 | #### Definition 1229 | Defined by the `Data Structures` keyword. 1230 | 1231 | # Data Structures 1232 | 1233 | #### Description 1234 | This section holds arbitrary data structures definitions defined in the form of 1235 | [MSON Named Types][]. 1236 | 1237 | Data structures defined in this section **may** be used in any [Attributes section][]. 1238 | Similarly, any data structures defined in a [Attributes section][] of a named 1239 | [Resource Section][] **may** be used in a data structure definition. 1240 | 1241 | Refer to the [MSON][] specification for full details on how to define an MSON Named type. 1242 | 1243 | #### Example 1244 | 1245 | ```apib 1246 | # Data Structures 1247 | 1248 | ## Message (object) 1249 | 1250 | + text (string) - text of the message 1251 | + author (Author) - author of the message 1252 | 1253 | ## Author (object) 1254 | 1255 | + name: John 1256 | + email: john@appleseed.com 1257 | ``` 1258 | 1259 | #### Example reusing Data Structure in Resource 1260 | 1261 | ```apib 1262 | # User [/user] 1263 | 1264 | + Attributes (Author) 1265 | 1266 | # Data Structures 1267 | 1268 | ## Author (object) 1269 | 1270 | + name: John 1271 | + email: john@appleseed.com 1272 | ``` 1273 | 1274 | #### Example reusing Resource-defined Data Structure 1275 | 1276 | ```apib 1277 | # User [/user] 1278 | 1279 | + Attributes 1280 | + name: John 1281 | + email: john@appleseed.com 1282 | 1283 | # Data Structures 1284 | 1285 | ## Author (User) 1286 | ``` 1287 | 1288 | --- 1289 | 1290 | 1291 | ## Relation section 1292 | - **Parent sections:** [Action section](#def-action-section) 1293 | - **Nested Sections:** none 1294 | - **Markdown entity:** list 1295 | - **Inherits from**: none 1296 | 1297 | #### Definition 1298 | Defined by the `Relation` keyword written in a Markdown list item followed by a 1299 | colon (`:`) and a link relation identifier. 1300 | 1301 | + Relation: 1302 | 1303 | #### Description 1304 | This section specifies a [link relation type](https://tools.ietf.org/html/rfc5988#section-4) 1305 | for the given action as specified by [RFC 5988](https://tools.ietf.org/html/rfc5988). 1306 | 1307 | > **NOTE:** The link relation identifiers should be unique per resource in the blueprint document. 1308 | 1309 | #### Example 1310 | 1311 | ```apib 1312 | # Task [/tasks/{id}] 1313 | 1314 | + Parameters 1315 | + id 1316 | 1317 | ## Retrieve Task [GET] 1318 | 1319 | + Relation: task 1320 | + Response 200 1321 | 1322 | { ... } 1323 | 1324 | ## Delete Task [DELETE] 1325 | 1326 | + Relation: delete 1327 | + Response 204 1328 | ``` 1329 | 1330 | --- 1331 | 1332 | 1333 |
1334 | 1335 | 1336 | # III. Appendix 1337 | 1338 | 1339 | ## URI Templates 1340 | 1341 | The API Blueprint uses a subset of [RFC6570][rfc6570] to define a resource URI Template. 1342 | 1343 | ### URI Path Segment 1344 | 1345 | At its simplest form – without any variables – a path segment of an 1346 | URI Template is identical to an URI path segment: 1347 | 1348 | ``` 1349 | /path/to/resources/42 1350 | ``` 1351 | 1352 | ### URI Template Variable 1353 | 1354 | Variable names are case-sensitive. The variable name may consists of following 1355 | characters **only**: 1356 | 1357 | - ASCII alpha numeric characters (`a-z`, `A-Z`) 1358 | - Decimal digits (`0-9`) 1359 | - `_` 1360 | - [Percent-encoded][pct-encoded] characters 1361 | - `.` 1362 | 1363 | Multiple variables are separated by the comma **without** any leading or 1364 | trailing spaces. A variable(s) **must** be enclosed in braces – `{}` 1365 | **without** any additional leading or trailing whitespace. 1366 | 1367 | #### Operators 1368 | 1369 | The first variable in the braces **might** be preceded by an operator. 1370 | API Blueprint currently supports the following operators: 1371 | 1372 | - `#` – _fragment identifier_ operator 1373 | - `+` – _reserved value_ operator 1374 | - `?` – _form-style query_ operator 1375 | - `&` – _form-style query continuation_ operator 1376 | 1377 | #### Examples 1378 | 1379 | ``` 1380 | {var} 1381 | {var1,var2,var3} 1382 | {#var} 1383 | {+var} 1384 | {?var} 1385 | {?var1,var2} 1386 | {?%24var} 1387 | {&var} 1388 | ``` 1389 | 1390 | > **NOTE:** The [explode variable modifier][uri-explode] is also supported. 1391 | > Refer to RFC6570 for its description. 1392 | 1393 | #### Variable Reserved Values 1394 | 1395 | Following characters are **reserved** in variable _values_: 1396 | 1397 | `:` / `/` / `?` / `#` / `[` / `]` / `@` / `!` / `$` / `&` / `'` / `(` / `)` / `*` / `+` / `,` / `;` / `=` 1398 | 1399 | ### Path Segment Variable 1400 | 1401 | Simple path segment component variable is defined without any operator: 1402 | 1403 | ``` 1404 | /path/to/resources/{var} 1405 | ``` 1406 | 1407 | With `var := 42` the expansion is `/path/to/resources/42`. 1408 | 1409 | > **NOTE:** RFC6570 – Level 1 1410 | 1411 | ### Fragment Identifier Variable 1412 | 1413 | URI Template variables for fragment identifiers are defined using the 1414 | crosshatch (`#`) operator: 1415 | 1416 | ``` 1417 | /path/to/resources/42{#var} 1418 | ``` 1419 | 1420 | With `var := my_id` the expansion is `/path/to/resources/42#my_id`. 1421 | 1422 | > **NOTE:** RFC6570 – Level 2 1423 | 1424 | ### Variable with Reserved Characters Values 1425 | 1426 | To define URI Template variables with reserved URI characters, 1427 | use the plus (`+`) operator: 1428 | 1429 | ``` 1430 | /path/{+var}/42 1431 | ``` 1432 | 1433 | With `var := to/resources` the expansion is `/path/to/resources/42`. 1434 | 1435 | > **NOTE:** RFC6570 – Level 2 1436 | 1437 | ### Form-style Query Variable 1438 | 1439 | To define variables for a form-style query use the question mark (`?`) operator 1440 | 1441 | ``` 1442 | /path/to/resources/{varone}{?vartwo} 1443 | ``` 1444 | 1445 | With `varone := 42` and `vartwo = hello` the expansion is `/path/to/resources/42?vartwo=hello`. 1446 | 1447 | To continue a form-style query use the ampersand (`&`) operator: 1448 | 1449 | ``` 1450 | /path/to/resources/{varone}?path=test{&vartwo,varthree} 1451 | ``` 1452 | 1453 | With `varone := 42`, `vartwo = hello`, `varthree = 1024` the expansion is `/path/to/resources/42?path=test&vartwo=hello&varthree=1024`. 1454 | 1455 | > **NOTE:** RFC6570 – Part of Level 3 1456 | 1457 | --- 1458 | 1459 | [apiblueprint.org]: http://apiblueprint.org 1460 | [markdown syntax]: http://daringfireball.net/projects/markdown 1461 | [reference syntax]: http://daringfireball.net/projects/markdown/syntax#link 1462 | [gitHub flavored markdown syntax]: https://help.github.com/articles/github-flavored-markdown 1463 | [httpmethods]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md#know-your-http-methods-well 1464 | [uritemplate]: #def-uri-templates 1465 | [rfc6570]: http://tools.ietf.org/html/rfc6570 1466 | [HTTP status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md 1467 | [header syntax]: https://daringfireball.net/projects/markdown/syntax#header 1468 | [list syntax]: https://daringfireball.net/projects/markdown/syntax#list 1469 | [pct-encoded]: http://en.wikipedia.org/wiki/Percent-encoding 1470 | [uri-explode]: http://tools.ietf.org/html/rfc6570#section-2.4.2 1471 | [examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples 1472 | 1473 | [MSON]: https://github.com/apiaryio/mson 1474 | [MSON Named Types]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#22-named-types 1475 | [MSON Type Definition]: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#35-type-definition 1476 | 1477 | [`0-1` Attributes section]: #def-attributes-section 1478 | [Attributes section]: #def-attributes-section 1479 | [Attributes sections]: #def-attributes-section 1480 | 1481 | [Resource Section]: #def-resource-section 1482 | 1483 | [Request section]: #def-request-section 1484 | -------------------------------------------------------------------------------- /Advanced Tutorial.md: -------------------------------------------------------------------------------- 1 | # Advanced API Blueprint Tutorial 2 | 3 | Welcome to the advanced API Blueprint tutorial! This tutorial will take you 4 | through advanced topics like JSON Schema, request and response attributes, data 5 | structures and relation types. 6 | 7 | This tutorial assumes that you have read the [API Blueprint Tutorial](https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md). 8 | 9 | ## JSON Schema 10 | 11 | Action request and response bodies can have associated schemas that describe 12 | the allowed structure of the body content. JSON bodies are typically described 13 | with [JSON Schema](http://json-schema.org/). Given a simple JSON response body 14 | we can describe the structure of the response with JSON Schema in a `+ Schema` 15 | section. 16 | 17 | The schema can describe the type of each member, which members are required, 18 | default values, and support a number of other advanced features. Below is an 19 | example, taken from the 20 | [Polls API](https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md) 21 | blueprint: 22 | 23 | ```apib 24 | ### Create a New Question [POST] 25 | You may create your own question using this action. It takes a JSON object 26 | containing a question and a collection of answers in the form of choices. 27 | 28 | + Request (application/json) 29 | 30 | + Body 31 | 32 | { 33 | "question": "Favourite language?" 34 | "choices": [ 35 | "Swift", 36 | "Objective-C" 37 | ] 38 | } 39 | 40 | + Schema 41 | 42 | { 43 | "$schema": "http://json-schema.org/draft-04/schema#", 44 | "type": "object", 45 | "properties": { 46 | "question": { 47 | "type": "string" 48 | }, 49 | "choices": { 50 | "type": "array", 51 | "items": { 52 | "type": "string" 53 | }, 54 | "minItems": 2 55 | } 56 | } 57 | } 58 | ``` 59 | 60 | ## Attributes 61 | 62 | Another way of describing examples and the structure of your request and 63 | response content is by using [MSON](https://github.com/apiaryio/mson#readme). 64 | MSON, like API Blueprint, allows you to use human-readable plain text to 65 | describe things rather than formats designed for computer parsing like JSON or 66 | YAML. Where API Blueprint allows you to describe your API, MSON allows you to 67 | describe data structures. 68 | 69 | MSON can be added to resources, actions, and individual requests or responses 70 | via an `+ Attributes` section. 71 | 72 | Creating a new question in the polls API can be modeled using MSON: 73 | 74 | ```apib 75 | ### Create a New Question [POST] 76 | You may create your own question using this action. It takes a JSON object 77 | containing a question and a collection of answers in the form of choices. 78 | 79 | + Request (application/json) 80 | 81 | + Attributes 82 | 83 | + question: Favourite Language? (required) 84 | + choices: Swift, `Objective-C` (array, required) 85 | 86 | ``` 87 | 88 | When the above blueprint is parsed it will have a JSON body and JSON Schema 89 | example generated for it from the MSON attributes. Note, however, that the 90 | generated JSON Schema may differ from a hand-written one. In this example, the 91 | `minItems` will not be set. If you have such constraints you can override the 92 | generated schema by providing your own, in which case only the JSON body will 93 | be generated. 94 | 95 | ## Data Structures 96 | 97 | Once you start using MSON, you may find yourself wanting to reuse certain 98 | commonly used or nested data structure components. This is possible with the 99 | `## Data Structures` section. Attributes sections can then reference the data 100 | structures defined in the Data Structures or other resource sections by name. 101 | 102 | For example, using the polls API question collection resource, we can split out 103 | the `Question` and `Choice` objects: 104 | 105 | ```apib 106 | ### List All Questions [GET] 107 | + Response 200 (application/json) 108 | 109 | + Attributes (array[Question]) 110 | 111 | ## Data Structures 112 | 113 | ### Question 114 | + question: Favourite programming language? (required) 115 | + published_at: `2014-11-11T08:40:51.620Z` (required) 116 | + url: /questions/1 (required) 117 | + choices (array[Choice], required) 118 | 119 | ### Choice 120 | + choice: Javascript (required) 121 | + url: /questions/1/choices/1 (required) 122 | + votes: 2048 (number, required) 123 | 124 | ``` 125 | 126 | ## Relation Types 127 | 128 | Actions in a blueprint can define a semantic domain-specific meaning by 129 | defining a relation type using a `+ Relation` section. This means that an 130 | action can have a specific meaning regardless of its URI or name, and allows 131 | clients to be built based on the domain of the API rather than specific URIs. 132 | 133 | For example, in the polls API: 134 | 135 | ```apib 136 | ## Question [/question/{id}] 137 | ### View a Question Detail [GET] 138 | + Relation: self 139 | 140 | ### Delete a Question [DELETE] 141 | + Relation: delete 142 | 143 | ## Questions Collection [/questions] 144 | ### List All Questions [GET] 145 | + Relation: self 146 | ``` 147 | 148 | A server or client implementation can now use this information to handle the 149 | specific API resource and action URIs. Please see the 150 | [Web Linking RFC 5988](https://tools.ietf.org/html/rfc5988) and the 151 | [IANA Link Relation Types](http://www.iana.org/assignments/link-relations/link-relations.xhtml) for 152 | more information. 153 | 154 | ## Conclusion 155 | 156 | This tutorial has covered some advanced API Blueprint topics. 157 | For more in-depth information and other advanced topics, 158 | please see the [API Blueprint Specification](https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md). 159 | -------------------------------------------------------------------------------- /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 16 | description. See [**API Blueprint**](#def-api-blueprint). 17 | 18 | 19 | ### API Blueprint 20 | The **API Blueprint language**. A format used to describe API in an API blueprint file. 21 | 22 | 23 | ### Asset 24 | **Atomic data**. Most often representing one resource representation in the form of message-body or its validation schema. 25 | 26 | 27 | ### Attribute 28 | Based on the context, attribute (property) of a message-body data structure, or 29 | attribute of a resource, or an input attribute of a transition – 30 | [Action](#def-action). 31 | 32 | 33 | ### Blueprint 34 | An **API description**. A **blueprint file** (or a set of files) that describes an API using the API Blueprint language. 35 | 36 | 37 | ### Data Structure 38 | A particular data organization, or a description of it. In API Blueprint, data 39 | structures and their [Attributes](#def-attribute) are described using the 40 | Markdown Syntax for Object Notation – [MSON][]. 41 | 42 | 43 | ### Entity 44 | [**Entity**](http://www.w3.org/Protocols/rfc2616/rfc2616-sec7.html) being transferred in a [payload](#def-payload). 45 | 46 | 47 | ### Header 48 | A [**message-header**](#def-message-header). 49 | 50 | 51 | ### Method 52 | An [**HTTP Request Method**](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods). 53 | 54 | 55 | ### Message 56 | An **HTTP transaction message**. 57 | 58 | 59 | ### Message body 60 | An [**asset**](#def-asset) representing [**HTTP transaction message body**](http://en.wikipedia.org/wiki/HTTP_body_data). 61 | 62 | 63 | ### Message header 64 | An [**asset**](#def-asset) representing [**HTTP transaction message header**](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields). 65 | 66 | ### Parameter 67 | An [**URI template**](#def-uri-template) **variable**. 68 | 69 | 70 | ### Payload 71 | An **HTTP transaction message** including its **discussion** and any additional [**assets**](#def-asset) such as entity-body validation schema. 72 | 73 | A payload may have an **identifier** – a string for a [request](#def-request) 74 | payload or an 75 | [HTTP status code](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes) for a 76 | [response](#def-response) payload. 77 | 78 | 79 | ### Property 80 | An [entity](#def-entity) field (attribute). 81 | 82 | 83 | ### Request 84 | A [**payload**](#def-payload) containing one specific [HTTP Request](http://www.w3.org/TR/di-gloss/#def-http-request). 85 | 86 | 87 | ### Response 88 | A [**payload**](#def-payload) containing one specific [HTTP Response](http://www.w3.org/TR/di-gloss/#def-http-response). 89 | 90 | 91 | ### Resource 92 | An API [**resource**](http://www.w3.org/TR/di-gloss/#def-resource) specified by 93 | its *URI*. It can also refer to a [**set of resources**](#def-resource) 94 | matching one [**URI template**](#def-uri-template). 95 | 96 | 97 | ### Resource Model 98 | One [**manifestation of a resource**](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) in the 99 | form of a [payload](#def-payload). A resource model is an example 100 | representation of its resource. Can be referenced later in the place of a 101 | [payload](#def-payload). 102 | 103 | 104 | ### Resource Set 105 | A set of API [**resources**](http://www.w3.org/TR/di-gloss/#def-resource). Its 106 | *URI* matches one specific [**URI template**](#def-uri-template). 107 | 108 | 109 | ### Trait 110 | A quality or characteristic of an API Blueprint SECTION. 111 | 112 | 113 | ### Schema 114 | A **validation schema** in a form of an [**asset**](#def-asset) used to validate (or describe) a [**message-body**](#def-message-body). 115 | 116 | 117 | ### URI template 118 | 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). 119 | 120 | ## Additional resources 121 | 122 | + [HTTP/1.1 Terminology](http://www.w3.org/Protocols/rfc2616/rfc2616-sec1.html#sec1.3) 123 | + [W3C Glossary of Terms for Device Independence](http://www.w3.org/TR/di-gloss) 124 | + [Know your HTTP well](https://github.com/for-GET/know-your-http-well) 125 | + [Markdown Syntax for Object Notation][MSON] 126 | 127 | 128 | 129 | [MSON]: https://github.com/apiaryio/mson 130 | 131 | -------------------------------------------------------------------------------- /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. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![logo](assets/logo_apiblueprint.png) 2 | 3 | # API Blueprint 4 | ### API Design for Humans 5 | 6 | A powerful high-level API design language for web APIs. 7 | 8 | API Blueprint is simple and accessible to everybody involved in the API design 9 | lifecycle. Its syntax is concise yet expressive. 10 | 11 | With API Blueprint you can quickly prototype and model APIs to be created or 12 | describe already deployed mission-critical APIs. From a [car][tesla] to the 13 | largest Content Distribution Network (CDN) in the world. 14 | 15 | The API Blueprint is built to encourage dialogue and collaboration between 16 | project stakeholders, developers and customers at any point in the API 17 | lifecycle. At the same time, the API Blueprint [tools][] provide the support to 18 | achieve the goals be it API development, governance or delivery. 19 | 20 | ![API Blueprint Lifecycle](assets/lifecycle.png) 21 | 22 | [tesla]: https://github.com/timdorr/model-s-api/blob/master/apiary.apib 23 | [tools]: http://apiblueprint.org/tools.html 24 | 25 | ## Open Source 26 | API Blueprint is completely open sourced under the MIT license. 27 | Any [contribution][contribute] is highly appreciated. 28 | 29 | [contribute]: #contribute 30 | 31 | ## At home on GitHub 32 | API Blueprint language is recognized by GitHub. You can 33 | [search for API Blueprint][search] or use the `apib` language identifier for 34 | [syntax highlighting][gfm]. 35 | 36 | [search]: https://github.com/search?utf8=%E2%9C%93&q=language%3A%22API+Blueprint%22&type=Repositories&ref=advsearch&l=API+Blueprint&l= 37 | 38 | [gfm]: https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting 39 | 40 | ## Getting started 41 | All it takes to describe an endpoint of your API is to write: 42 | 43 | ```apib 44 | # GET /message 45 | + Response 200 (text/plain) 46 | 47 | Hello World! 48 | ``` 49 | 50 | in your favorite plain text editor. 51 | 52 | With this blueprint you can already get a [mock][], [documentation][] and 53 | [test][] for your API before you even start coding. 54 | 55 | To learn more about the API Blueprint syntax jump directly to the 56 | [API Blueprint Tutorial][tutorial] or take a look at some [examples][]. 57 | 58 | [mock]: http://docs.apibstart.apiary.io/#reference/0/message/get?console=1 59 | [documentation]: https://apiblueprint.org/documentation/ 60 | [test]: http://dredd.readthedocs.org/en/latest/ 61 | [tutorial]: Tutorial.md 62 | [examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples 63 | 64 | ## Media Type 65 | The media type for API Blueprint is `text/vnd.apiblueprint`. 66 | 67 | ## Learn more 68 | - [Tutorial][tutorial] 69 | - [Advanced Tutorial][advanced_tutorial] 70 | - [Examples][examples] 71 | - [Wiki][wiki] 72 | - [Glossary of Terms][glossary] 73 | - [Specification][specification] 74 | - [List of Tools][tools] 75 | - [Developers][developers] 76 | 77 | [advanced_tutorial]: Advanced%20Tutorial.md 78 | [glossary]: Glossary%20of%20Terms.md 79 | [specification]: API%20Blueprint%20Specification.md 80 | [wiki]: https://github.com/apiaryio/api-blueprint/wiki 81 | [developers]: https://apiblueprint.org/developers.html 82 | 83 | ## Future 84 | The plans for API Blueprint are completely tracked on GitHub – see the 85 | [API Blueprint Roadmap][roadmap]. 86 | 87 | [roadmap]: https://github.com/apiaryio/api-blueprint/wiki/Roadmap 88 | 89 | ## Developers 90 | Building tools for API Blueprint is possible thanks to its machine-friendly face 91 | provided by API Blueprint parser. 92 | 93 | If you are interested in building tools for API Blueprint check out the 94 | [Developing tools for API Blueprint][developers]. 95 | 96 | ## Contribute 97 | Feel free report problems or propose new ideas using the API Blueprint GitHub 98 | [issues][]. 99 | 100 | We use an RFC process for proposing any substantial changes to the API 101 | Blueprint language, specification and/or parsers. 102 | 103 | If you would like to propose a change, please consult our 104 | [RFC process][rfc]. 105 | 106 | [issues]: https://github.com/apiaryio/api-blueprint/issues 107 | [rfc]: https://github.com/apiaryio/api-blueprint-rfcs 108 | 109 | ## Get in Touch 110 | - [@apiblueprint](https://twitter.com/apiblueprint) 111 | - [Slack](https://apiblueprint-slack.herokuapp.com/) 112 | - [Stack Overflow](http://stackoverflow.com/questions/tagged/apiblueprint) 113 | - [GitHub Issues][issues] 114 | 115 | ## License 116 | MIT License. See the [LICENSE](https://github.com/apiaryio/api-blueprint/blob/master/LICENSE) 117 | file. 118 | -------------------------------------------------------------------------------- /Tutorial.md: -------------------------------------------------------------------------------- 1 | # API Blueprint Tutorial 2 | 3 | Welcome to an API Blueprint Tutorial! This tutorial will take you through the 4 | basics of the API Blueprint language. We’re going to build an API blueprint 5 | step by step for a service called Polls – a simple API allowing consumers to 6 | view polls and vote in them. You can take a look at the 7 | [full version][Poll API Blueprint] of the blueprint used in this tutorial for 8 | reference. 9 | 10 | > **Note:** **Additional API Blueprint Resources** 11 | > 12 | > + [Language Specification][specification] 13 | > + [Examples][API Blueprint Examples] 14 | > + [Glossary of Terms][API Blueprint Glossary of Terms] 15 | > + [API Blueprint Map][map] 16 | > + [Tools for API Blueprint][Tooling Section] 17 | 18 | ## API Blueprint 19 | 20 | The first step for creating a blueprint is to specify the API Name and 21 | metadata. This step looks as follows: 22 | 23 | ```apib 24 | FORMAT: 1A 25 | 26 | # Polls 27 | 28 | Polls is a simple API allowing consumers to view polls and vote in them. 29 | ``` 30 | 31 | ## Metadata 32 | 33 | The blueprint starts with a metadata section. In this case we have specified 34 | that `FORMAT` has the value of `1A`. The format keyword denotes the version of 35 | the API Blueprint. 36 | 37 | ## API Name & Description 38 | 39 | The first heading in the blueprint serves as the name of your API, which in 40 | this case is "Polls". Headings start with one or more `#` symbols followed by a 41 | title. The API Name here uses one hash to distinguish it as the first level. 42 | The number of `#` you use will determine the level of the heading. 43 | 44 | Following the heading is a description of the API. You may use further headings 45 | to break up the description section. 46 | 47 | ## Resource Groups 48 | 49 | Now it's time to start documenting the API resources. Using the `Group` keyword 50 | at the start of a heading, we've created a group of related resources. 51 | 52 | ```apib 53 | # Group Questions 54 | 55 | Resources related to questions in the API. 56 | ``` 57 | 58 | ## Resource 59 | 60 | Within the questions resource group, we have a resource called "Question 61 | Collection". This resource allows you to view a list of questions. The heading 62 | specifies the URI used to access the resource inside of square brackets at the 63 | end of the heading. 64 | 65 | ```apib 66 | ## Question Collection [/questions] 67 | ``` 68 | 69 | ### Actions 70 | 71 | API Blueprint allows you to specify each action you may make on a resource. An 72 | action is specified with a sub-heading inside of a resource with the name of 73 | the action followed by the HTTP method. 74 | 75 | ```apib 76 | ### List All Questions [GET] 77 | ``` 78 | 79 | An action should include at least one response from the server which must 80 | include a status code and may contain a body. A response is defined as a list 81 | item within an action. Lists are created by preceding list items with either a 82 | `+`, `*` or `-`. 83 | 84 | This action returns a `200` status code along with a JSON body. 85 | 86 | ```apib 87 | + Response 200 (application/json) 88 | 89 | [ 90 | { 91 | "question": "Favourite programming language?", 92 | "published_at": "2014-11-11T08:40:51.620Z", 93 | "url": "/questions/1", 94 | "choices": [ 95 | { 96 | "choice": "Swift", 97 | "url": "/questions/1/choices/1", 98 | "votes": 2048 99 | }, { 100 | "choice": "Python", 101 | "url": "/questions/1/choices/2", 102 | "votes": 1024 103 | }, { 104 | "choice": "Objective-C", 105 | "url": "/questions/1/choices/3", 106 | "votes": 512 107 | }, { 108 | "choice": "Ruby", 109 | "url": "/questions/1/choices/4", 110 | "votes": 256 111 | } 112 | ] 113 | } 114 | ] 115 | ``` 116 | 117 | > **Note:** Specifying the media type after the response status code generates 118 | > a `Content-Type` HTTP header. You do not have to explicitly specify the 119 | > `Content-Type` header. 120 | 121 | The polls resource has a second action which allows you to create a new 122 | question. This action includes a description showing the structure you would 123 | send to the server to perform this action. 124 | 125 | ```apib 126 | ### Create a New Question [POST] 127 | 128 | You may create your own question using this action. It takes a JSON object 129 | containing a question and a collection of answers in the form of choices. 130 | 131 | + question (string) - The question 132 | + choices (array[string]) - A collection of choices. 133 | ``` 134 | 135 | This action takes a JSON payload as part of the request as follows: 136 | 137 | ```apib 138 | + Request (application/json) 139 | 140 | { 141 | "question": "Favourite programming language?", 142 | "choices": [ 143 | "Swift", 144 | "Python", 145 | "Objective-C", 146 | "Ruby" 147 | ] 148 | } 149 | ``` 150 | 151 | This example returns a `201` status code, along with HTTP headers and a body. 152 | 153 | ```apib 154 | + Response 201 (application/json) 155 | 156 | + Headers 157 | 158 | Location: /questions/1 159 | 160 | + Body 161 | 162 | { 163 | "question": "Favourite programming language?", 164 | "published_at": "2014-11-11T08:40:51.620Z", 165 | "url": "/questions/1", 166 | "choices": [ 167 | { 168 | "choice": "Swift", 169 | "url": "/questions/1/choices/1", 170 | "votes": 0 171 | }, { 172 | "choice": "Python", 173 | "url": "/questions/1/choices/2", 174 | "votes": 0 175 | }, { 176 | "choice": "Objective-C", 177 | "url": "/questions/1/choices/3", 178 | "votes": 0 179 | }, { 180 | "choice": "Ruby", 181 | "url": "/questions/1/choices/4", 182 | "votes": 0 183 | } 184 | ] 185 | } 186 | ``` 187 | 188 | The next resource is “Question”, which represents a single question. 189 | 190 | ```apib 191 | ## Question [/questions/{question_id}] 192 | ``` 193 | 194 | ### URI Template 195 | 196 | The URI for the “Question” resource uses a variable component, expressed by 197 | [URI Template][]. In this case, there is an ID variable called `question_id`, 198 | represented in the URI template as `{question_id}`. 199 | 200 | 201 | ### URI Parameters 202 | 203 | URI parameters should describe the URI using a list of Parameters. For 204 | “Question” it would be as follows: 205 | 206 | ```apib 207 | + Parameters 208 | + question_id (number) - ID of the Question in the form of an integer 209 | ``` 210 | 211 | The `question_id` variable of the URI template is a parameter for every action 212 | on this resource. It's defined here using an arbitrary type `number`, followed 213 | by a description for the parameter. 214 | 215 | > Refer to API Blueprint Specification's [URI Parameters Section][] for more 216 | > examples. 217 | 218 | ### Actions 219 | 220 | This resource has an action to retrieve the question's detail. 221 | 222 | ```apib 223 | ### View a Questions Detail [GET] 224 | 225 | + Response 200 (application/json) 226 | 227 | { 228 | "question": "Favourite programming language?", 229 | "published_at": "2014-11-11T08:40:51.620Z", 230 | "url": "/questions/1", 231 | "choices": [ 232 | { 233 | "choice": "Swift", 234 | "url": "/questions/1/choices/1", 235 | "votes": 2048 236 | }, { 237 | "choice": "Python", 238 | "url": "/questions/1/choices/2", 239 | "votes": 1024 240 | }, { 241 | "choice": "Objective-C", 242 | "url": "/questions/1/choices/3", 243 | "votes": 512 244 | }, { 245 | "choice": "Ruby", 246 | "url": "/questions/1/choices/4", 247 | "votes": 256 248 | } 249 | ] 250 | } 251 | ``` 252 | 253 | #### Response Without a Body 254 | 255 | This resource has a delete action. The server will return a 204 response 256 | without a body. 257 | 258 | ```apib 259 | ### Delete [DELETE] 260 | 261 | + Response 204 262 | ``` 263 | 264 | ## Complete Blueprint 265 | 266 | You can find an [implementation](http://github.com/apiaryio/polls-api) of this 267 | API at http://polls.apiblueprint.org/ along with the complete 268 | [Poll API Blueprint][] in the [API Blueprint Examples][] repository. You can 269 | also enjoy it [rendered on Apiary][]. 270 | 271 | > **Note:** Take a look at the [API Blueprint Glossary of Terms][] if you need 272 | > clarification of some of the terms used though this document. 273 | 274 | ## API Blueprint Tools 275 | 276 | Visit the [Tooling Section][] of [apiblueprint.org][] to find tools to use with 277 | API Blueprints. 278 | 279 | [GitHub Gists]: https://gist.github.com 280 | [API Blueprint Glossary of Terms]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md 281 | [API Blueprint Identifier]: https://github.com/apiaryio/api-blueprint/blob/1A/API%20Blueprint%20Specification.md#Identifiers 282 | [HTTP Request Method]: https://github.com/for-GET/know-your-http-well/blob/master/methods.md 283 | [status code]: https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md 284 | [message-headers]: https://github.com/for-GET/know-your-http-well/blob/master/headers.md 285 | [payload]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#payload 286 | [URI Template]: https://github.com/apiaryio/api-blueprint/blob/master/Glossary%20of%20Terms.md#uri-template 287 | [URI Parameters Section]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def-uriparameters-section 288 | [Markdown pre-formatted code blocks]: http://daringfireball.net/projects/markdown/syntax#precode 289 | [URI Parameters]: #uri-parameters 290 | [API Blueprint Examples]: https://github.com/apiaryio/api-blueprint/tree/master/examples 291 | [Poll API Blueprint]: https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md 292 | [rendered on Apiary]: http://docs.pollsapi.apiary.io 293 | [Tooling Section]: http://apiblueprint.org/tools.html 294 | [apiblueprint.org]: http://apiblueprint.org 295 | [specification]: https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md 296 | [map]: https://github.com/apiaryio/api-blueprint/wiki/API-Blueprint-Map 297 | -------------------------------------------------------------------------------- /assets/lifecycle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/apiaryio/api-blueprint/86fc3a128a939e3b476ffc2e2819e54e20f3b45b/assets/lifecycle.png -------------------------------------------------------------------------------- /assets/logo_apiblueprint.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/apiaryio/api-blueprint/86fc3a128a939e3b476ffc2e2819e54e20f3b45b/assets/logo_apiblueprint.png -------------------------------------------------------------------------------- /assets/map.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/apiaryio/api-blueprint/86fc3a128a939e3b476ffc2e2819e54e20f3b45b/assets/map.png -------------------------------------------------------------------------------- /examples/01. Simplest API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # The Simplest API 4 | This is one of the simplest APIs written in the **API Blueprint**. One plain 5 | resource combined with a method and that's it! We will explain what is going on 6 | in the next installment - 7 | [Resource and Actions](02.%20Resource%20and%20Actions.md). 8 | 9 | **Note:** As we progress through the examples, do not also forget to view the 10 | [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) 11 | code to see what is really going on in the API Blueprint, as opposed to just 12 | seeing the output of the Github Markdown parser. 13 | 14 | Also please keep in mind that every single example in this course is a **real 15 | API Blueprint** and as such you can **parse** it with the 16 | [API Blueprint parser](https://github.com/apiaryio/drafter) or one of its 17 | [bindings](https://github.com/apiaryio/drafter#bindings). 18 | 19 | ## API Blueprint 20 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) 21 | + [Next: Resource and Actions](02.%20Resource%20and%20Actions.md) 22 | 23 | # GET /message 24 | + Response 200 (text/plain) 25 | 26 | Hello World! 27 | -------------------------------------------------------------------------------- /examples/02. 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](01.%20Simplest%20API.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/02.%20Resource%20and%20Actions.md) 9 | + [Next: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md) 10 | 11 | # /message 12 | This is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is 13 | defined by its 14 | [URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more 15 | precisely, by its [URI Template](http://tools.ietf.org/html/rfc6570). 16 | 17 | This resource has no actions specified but we will fix that soon. 18 | 19 | ## GET 20 | Here we define an action using the `GET` [HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`. 21 | 22 | As with every good action it should return a 23 | [response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always 24 | bears a status code. Code 200 is great as it means all is green. Responding 25 | with some data can be a great idea as well so let's add a plain text message to 26 | our response. 27 | 28 | + Response 200 (text/plain) 29 | 30 | Hello World! 31 | 32 | ## PUT 33 | OK, let's add another action. This time to put new data to our resource 34 | (essentially an update action). We will need to send something in a 35 | [request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a 36 | response back confirming the posting was a success (_HTTP Status Code 204 ~ 37 | Resource updated successfully, no content is returned_). 38 | 39 | + Request (text/plain) 40 | 41 | All your base are belong to us. 42 | 43 | + Response 204 44 | -------------------------------------------------------------------------------- /examples/03. 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 5 | the reader a better idea about what the resource is used for. 6 | 7 | ## API Blueprint 8 | + [Previous: Resource and Actions](02.%20Resource%20and%20Actions.md) 9 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/03.%20Named%20Resource%20and%20Actions.md) 10 | + [Next: Grouping Resources](04.%20Grouping%20Resources.md) 11 | 12 | # My Message [/message] 13 | OK, `My Message` probably isn't the best name for our resource but it will do 14 | for now. Note the URI `/message` is enclosed in square brackets. 15 | 16 | ## Retrieve a Message [GET] 17 | Now this is informative! No extra explanation needed here. This action clearly 18 | retrieves the message. 19 | 20 | + Response 200 (text/plain) 21 | 22 | Hello World! 23 | 24 | ## Update a Message [PUT] 25 | `Update a message` - nice and simple naming is the best way to go. 26 | 27 | + Request (text/plain) 28 | 29 | All your base are belong to us. 30 | 31 | + Response 204 32 | -------------------------------------------------------------------------------- /examples/04. Grouping Resources.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Grouping Resources API 4 | This API example demonstrates how to group resources and form **groups of 5 | resources**. You can create as many or as few groups as you like. If you do not 6 | create any group all your resources will be part of an "unnamed" group. 7 | 8 | ## API Blueprint 9 | + [Previous: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/04.%20Grouping%20Resources.md) 11 | + [Next: Responses](05.%20Responses.md) 12 | 13 | # Group Messages 14 | Group of all messages-related resources. 15 | 16 | This is the first group of resources in this document. It is **recognized** by 17 | the **keyword `group`** and its name is `Messages`. 18 | 19 | Any following resource definition is considered to be a part of this group 20 | until another group is defined. It is **customary** to increase header level of 21 | resources (and actions) nested under a resource. 22 | 23 | ## My Message [/message] 24 | 25 | ### Retrieve a Message [GET] 26 | 27 | + Response 200 (text/plain) 28 | 29 | Hello World! 30 | 31 | ### Update a Message [PUT] 32 | 33 | + Request (text/plain) 34 | 35 | All your base are belong to us. 36 | 37 | + Response 204 38 | 39 | # Group Users 40 | Group of all user-related resources. 41 | 42 | This is the second group in this blueprint. For now, no resources were defined 43 | here and as such we will omit it from the next installment of this course. 44 | -------------------------------------------------------------------------------- /examples/05. Responses.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Responses API 4 | In this API example we will discuss what information a response can bear and 5 | how to define multiple responses. Technically a response is represented by a 6 | payload that is sent back in response to a request. 7 | 8 | ## API Blueprint 9 | + [Previous: Grouping Resources](04.%20Grouping%20Resources.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/05.%20Responses.md) 11 | + [Next: Requests](06.%20Requests.md) 12 | 13 | # Group Messages 14 | Group of all messages-related resources. 15 | 16 | ## My Message [/message] 17 | 18 | ### Retrieve a Message [GET] 19 | This action has **two** responses defined: One returning plain text and the 20 | other a JSON representation of our resource. Both have the same HTTP status 21 | code. Also both responses bear additional information in the form of a custom 22 | HTTP header. Note that both responses have set the `Content-Type` HTTP header 23 | just by specifying `(text/plain)` or `(application/json)` in their respective 24 | signatures. 25 | 26 | + Response 200 (text/plain) 27 | 28 | + Headers 29 | 30 | X-My-Message-Header: 42 31 | 32 | + Body 33 | 34 | Hello World! 35 | 36 | + Response 200 (application/json) 37 | 38 | + Headers 39 | 40 | X-My-Message-Header: 42 41 | 42 | + Body 43 | 44 | { "message": "Hello World!" } 45 | 46 | ### Update a Message [PUT] 47 | 48 | + Request (text/plain) 49 | 50 | All your base are belong to us. 51 | 52 | + Response 204 53 | -------------------------------------------------------------------------------- /examples/06. Requests.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Requests API 4 | Following the [Responses](05.%20Responses.md) example, this API will show you 5 | how to define multiple requests and what data these requests can bear. Let's 6 | demonstrate multiple requests on a trivial example of content negotiation. 7 | 8 | ## API Blueprint 9 | + [Previous: Responses](05.%20Responses.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/06.%20Requests.md) 11 | + [Next: Parameters](07.%20Parameters.md) 12 | 13 | # Group Messages 14 | Group of all messages-related resources. 15 | 16 | ## My Message [/message] 17 | 18 | ### Retrieve a Message [GET] 19 | In API Blueprint, _requests_ can hold exactly the same kind of information and 20 | can be described using exactly the same structure as _responses_, only with 21 | different signature – using the `Request` keyword. The string that follows 22 | after the `Request` keyword is a request identifier. Again, using explanatory 23 | and simple naming is the best way to go. 24 | 25 | + Request Plain Text Message 26 | 27 | + Headers 28 | 29 | Accept: text/plain 30 | 31 | + Response 200 (text/plain) 32 | 33 | + Headers 34 | 35 | X-My-Message-Header: 42 36 | 37 | + Body 38 | 39 | Hello World! 40 | 41 | + Request JSON Message 42 | 43 | + Headers 44 | 45 | Accept: application/json 46 | 47 | + Response 200 (application/json) 48 | 49 | + Headers 50 | 51 | X-My-Message-Header: 42 52 | 53 | + Body 54 | 55 | { "message": "Hello World!" } 56 | 57 | ### Update a Message [PUT] 58 | 59 | + Request Update Plain Text Message (text/plain) 60 | 61 | All your base are belong to us. 62 | 63 | + Request Update JSON Message (application/json) 64 | 65 | { "message": "All your base are belong to us." } 66 | 67 | + Response 204 68 | -------------------------------------------------------------------------------- /examples/07. Parameters.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Parameters API 4 | In this installment of the API Blueprint course we will discuss how to describe URI parameters. 5 | 6 | But first let's add more messages to our system. For that we would need 7 | introduce an message identifier – id. This id will be our parameter when 8 | communicating with our API about messages. 9 | 10 | ## API Blueprint 11 | + [Previous: Requests](06.%20Requests.md) 12 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/07.%20Parameters.md) 13 | + [Next: Attributes](08.%20Attributes.md) 14 | 15 | # Group Messages 16 | Group of all messages-related resources. 17 | 18 | ## My Message [/message/{id}] 19 | Here we have added the message `id` parameter as an 20 | [URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message 21 | resource's URI. Note the parameter name `id` is enclosed in curly brackets. We 22 | will discuss this parameter in the `Parameters` section below, where we will 23 | also set its example value to `1` and declare it of an arbitrary 'number' type. 24 | 25 | + Parameters 26 | 27 | + id: 1 (number) - An unique identifier of the message. 28 | 29 | ### Retrieve a Message [GET] 30 | 31 | + Request Plain Text Message 32 | 33 | + Headers 34 | 35 | Accept: text/plain 36 | 37 | + Response 200 (text/plain) 38 | 39 | + Headers 40 | 41 | X-My-Message-Header: 42 42 | 43 | + Body 44 | 45 | Hello World! 46 | 47 | + Request JSON Message 48 | 49 | + Headers 50 | 51 | Accept: application/json 52 | 53 | + Response 200 (application/json) 54 | 55 | + Headers 56 | 57 | X-My-Message-Header: 42 58 | 59 | + Body 60 | 61 | { 62 | "id": 1, 63 | "message": "Hello World!" 64 | } 65 | 66 | ### Update a Message [PUT] 67 | 68 | + Request Update Plain Text Message (text/plain) 69 | 70 | All your base are belong to us. 71 | 72 | + Request Update JSON Message (application/json) 73 | 74 | { "message": "All your base are belong to us." } 75 | 76 | + Response 204 77 | 78 | ## All My Messages [/messages{?limit}] 79 | A resource representing all of my messages in the system. 80 | 81 | We have added the query URI template parameter - `limit`. This parameter is 82 | used for limiting the number of results returned by some actions on this 83 | resource. It does not affect every possible action of this resource, therefore 84 | we will discuss it only at the particular action level below. 85 | 86 | ### Retrieve all Messages [GET] 87 | 88 | + Parameters 89 | 90 | + limit (number, optional) - The maximum number of results to return. 91 | + Default: `20` 92 | 93 | + Response 200 (application/json) 94 | 95 | [ 96 | { 97 | "id": 1, 98 | "message": "Hello World!" 99 | }, 100 | { 101 | "id": 2, 102 | "message": "Time is an illusion. Lunchtime doubly so." 103 | }, 104 | { 105 | "id": 3, 106 | "message": "So long, and thanks for all the fish." 107 | } 108 | ] 109 | -------------------------------------------------------------------------------- /examples/08. Attributes.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Attributes API 4 | This API example demonstrates how to describe body attributes of a request or 5 | response message. 6 | 7 | In this case, the description is complementary (and duplicate!) to the provided 8 | JSON example in the body section. The 9 | [Advanced Attributes](09.%20Advanced%20Attributes.md) API example will 10 | demonstrate how to avoid duplicates and how to reuse attribute descriptions. 11 | 12 | ## API Blueprint 13 | + [Previous: Parameters](07.%20Parameters.md) 14 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/08.%20Attributes.md) 15 | + [Next: Advanced Attributes](09.%20Advanced%20Attributes.md) 16 | 17 | # Group Coupons 18 | 19 | ## Coupon [/coupons/{id}] 20 | A coupon contains information about a percent-off or amount-off discount you 21 | might want to apply to a customer. 22 | 23 | ### Retrieve a Coupon [GET] 24 | Retrieves the coupon with the given ID. 25 | 26 | + Response 200 (application/json) 27 | 28 | + Attributes (object) 29 | + id: 250FF (string, required) 30 | + created: 1415203908 (number) - Time stamp 31 | + percent_off: 25 (number) 32 | 33 | A positive integer between 1 and 100 that represents the discount 34 | the coupon will apply. 35 | 36 | + redeem_by (number) - Date after which the coupon can no longer be redeemed 37 | 38 | + Body 39 | 40 | { 41 | "id": "250FF", 42 | "created": 1415203908, 43 | "percent_off": 25, 44 | "redeem_by": null 45 | } 46 | -------------------------------------------------------------------------------- /examples/09. Advanced Attributes.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Advanced Attributes API 4 | Improving the previous [Attributes](08.%20Attributes.md) description example, 5 | this API example describes the `Coupon` resource attributes (data structure) 6 | regardless of the serialization format. These attributes can be later 7 | referenced using the resource name. 8 | 9 | These attributes are then reused in the `Retrieve a Coupon` action. Since they 10 | describe the complete message, no explicit JSON body example is needed. 11 | 12 | Moving forward, the `Coupon` resource data structure is then reused when 13 | defining the attributes of the coupons collection resource – `Coupons`. 14 | 15 | The `Create a Coupon` action also demonstrate the description of request 16 | attributes – once defined, these attributes are implied on every `Create a 17 | Coupon` request unless the request specifies otherwise. Apparently, the 18 | description of action attributes is somewhat duplicate to the definition of 19 | `Coupon` resource attributes. We will address this in the next 20 | [Data Structures](10.%20Data%20Structures.md) example. 21 | 22 | ## API Blueprint 23 | + [Previous: Attributes](08.%20Attributes.md) 24 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md) 25 | + [Next: Data Structures](10.%20Data%20Structures.md) 26 | 27 | # Group Coupons 28 | 29 | ## Coupon [/coupons/{id}] 30 | A coupon contains information about a percent-off or amount-off discount you 31 | might want to apply to a customer. 32 | 33 | + Parameters 34 | + id (string) 35 | 36 | The ID of the desired coupon. 37 | 38 | + Attributes (object) 39 | + id: 250FF (string, required) 40 | + created: 1415203908 (number) - Time stamp 41 | + percent_off: 25 (number) 42 | 43 | A positive integer between 1 and 100 that represents the discount the coupon will apply. 44 | 45 | + redeem_by (number) - Date after which the coupon can no longer be redeemed 46 | 47 | ### Retrieve a Coupon [GET] 48 | Retrieves the coupon with the given ID. 49 | 50 | + Response 200 (application/json) 51 | + Attributes (Coupon) 52 | 53 | ## Coupons [/coupons{?limit}] 54 | 55 | + Attributes (array[Coupon]) 56 | 57 | ### List all Coupons [GET] 58 | Returns a list of your coupons. 59 | 60 | + Parameters 61 | + limit (number, optional) 62 | 63 | A limit on the number of objects to be returned. Limit can range 64 | between 1 and 100 items. 65 | 66 | + Default: `10` 67 | 68 | + Response 200 (application/json) 69 | + Attributes (Coupons) 70 | 71 | ### Create a Coupon [POST] 72 | Creates a new Coupon. 73 | 74 | + Attributes (object) 75 | + percent_off: 25 (number) 76 | + redeem_by (number) 77 | 78 | + Request (application/json) 79 | 80 | + Response 200 (application/json) 81 | + Attributes (Coupon) 82 | -------------------------------------------------------------------------------- /examples/10. Data Structures.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Data Structures API 4 | Following [Advanced Attributes](09.%20Advanced%20Attributes.md), this example 5 | demonstrates defining arbitrary data structure to be reused by various 6 | attribute descriptions. 7 | 8 | Since a portion of the `Coupon` data structure is shared between the `Coupon` 9 | definition itself and the `Create a Coupon` action, it was separated into a 10 | `Coupon Base` data structure in the `Data Structures` API Blueprint Section. 11 | Doing so enables us to reuse it as a base-type of other attribute definitions. 12 | 13 | ## API Blueprint 14 | + [Previous: Advanced Attributes](09.%20Advanced%20Attributes.md) 15 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/10.%20Data%20Structures.md) 16 | + [Next: Resource Model](11.%20Resource%20Model.md) 17 | 18 | # Group Coupons 19 | 20 | ## Coupon [/coupons/{id}] 21 | A coupon contains information about a percent-off or amount-off discount you 22 | might want to apply to a customer. 23 | 24 | + Parameters 25 | + id (string) 26 | 27 | The ID of the desired coupon. 28 | 29 | + Attributes (Coupon Base) 30 | + id: 250FF (string, required) 31 | + created: 1415203908 (number) - Time stamp 32 | 33 | ### Retrieve a Coupon [GET] 34 | Retrieves the coupon with the given ID. 35 | 36 | + Response 200 (application/json) 37 | + Attributes (Coupon) 38 | 39 | ## Coupons [/coupons{?limit}] 40 | 41 | + Attributes (array[Coupon]) 42 | 43 | ### List all Coupons [GET] 44 | Returns a list of your coupons. 45 | 46 | + Parameters 47 | + limit (number, optional) 48 | 49 | A limit on the number of objects to be returned. Limit can range 50 | between 1 and 100 items. 51 | 52 | + Default: `10` 53 | 54 | + Response 200 (application/json) 55 | + Attributes (Coupons) 56 | 57 | ### Create a Coupon [POST] 58 | Creates a new Coupon. 59 | 60 | + Attributes (Coupon Base) 61 | 62 | + Request (application/json) 63 | 64 | + Response 200 (application/json) 65 | + Attributes (Coupon) 66 | 67 | # Data Structures 68 | 69 | ## Coupon Base (object) 70 | + percent_off: 25 (number) 71 | 72 | A positive integer between 1 and 100 that represents the discount the 73 | coupon will apply. 74 | 75 | + redeem_by (number) - Date after which the coupon can no longer be redeemed 76 | -------------------------------------------------------------------------------- /examples/11. 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). 5 | One particular representation of your resource. 6 | 7 | Furthermore, in API Blueprint, any `resource model` you have defined can be 8 | referenced in a request or response section, saving you lots of time 9 | maintaining your API blueprint. You simply define a resource model as any 10 | payload (e.g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/06.%20Requests.md) 11 | or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) 12 | and then reference it later where you would normally write a `request` or 13 | `response`. 14 | 15 | ## API Blueprint 16 | + [Previous: Data Structures](10.%20Data%20Structures.md) 17 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/11.%20Resource%20Model.md) 18 | + [Next: Advanced Action](12.%20Advanced%20Action.md) 19 | 20 | # Group Messages 21 | Group of all messages-related resources. 22 | 23 | ## My Message [/message] 24 | 25 | + Model (application/vnd.siren+json) 26 | 27 | This is the `application/vnd.siren+json` message resource representation. 28 | 29 | + Headers 30 | 31 | Location: http://api.acme.com/message 32 | 33 | + Body 34 | 35 | { 36 | "class": [ "message" ], 37 | "properties": { 38 | "message": "Hello World!" 39 | }, 40 | "links": [ 41 | { "rel": "self" , "href": "/message" } 42 | ] 43 | } 44 | 45 | ### Retrieve a Message [GET] 46 | At this point we will utilize our `Message` resource model and reference it in 47 | `Response 200`. 48 | 49 | + Response 200 50 | 51 | [My Message][] 52 | 53 | ### Update a Message [PUT] 54 | 55 | + Request Update Plain Text Message (text/plain) 56 | 57 | All your base are belong to us. 58 | 59 | + Request Update JSON Message (application/json) 60 | 61 | { "message": "All your base are belong to us." } 62 | 63 | + Response 204 64 | 65 | -------------------------------------------------------------------------------- /examples/12. Advanced Action.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Advanced Action API 4 | A resource action is – in fact – a state transition. This API example 5 | demonstrates an action - state transition - to another resource. 6 | 7 | ## API Blueprint 8 | + [Previous: Resource Model](11.%20Resource%20Model.md) 9 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/12.%20Advanced%20Action.md) 10 | + [Next: Named Endpoints](13.%20Named%20Endpoints.md) 11 | 12 | # Tasks [/tasks/tasks{?status,priority}] 13 | 14 | + Parameters 15 | + status (string) 16 | + priority (number) 17 | 18 | ## List All Tasks [GET] 19 | 20 | + Response 200 (application/json) 21 | 22 | [ 23 | { 24 | "id": 123, 25 | "name": "Exercise in gym", 26 | "done": false, 27 | "type": "task" 28 | }, 29 | { 30 | "id": 124, 31 | "name": "Shop for groceries", 32 | "done": true, 33 | "type": "task" 34 | } 35 | ] 36 | 37 | ## Retrieve Task [GET /task/{id}] 38 | This is a state transition to another resource. 39 | 40 | + Parameters 41 | + id (string) 42 | 43 | + Response 200 (application/json) 44 | 45 | { 46 | "id": 123, 47 | "name": "Go to gym", 48 | "done": false, 49 | "type": "task" 50 | } 51 | 52 | ## Delete Task [DELETE /task/{id}] 53 | 54 | + Parameters 55 | + id (string) 56 | 57 | + Response 204 58 | -------------------------------------------------------------------------------- /examples/13. Named Endpoints.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Named Endpoints API 4 | This API example demonstrates how to define a standalone endpoint with an identifier. 5 | 6 | ## API Blueprint 7 | + [Previous: Advanced Action](12.%20Advanced%20Action.md) 8 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/13.%20Named%20Endpoints.md) 9 | + [Next: JSON Schema](14.%20JSON%20Schema.md) 10 | 11 | # Group Quick start 12 | 13 | ## Create message [POST /messages] 14 | 15 | Start out by creating a message for the world to see. 16 | 17 | + Request (application/json) 18 | 19 | { "message": "Hello World!" } 20 | 21 | + Response 201 22 | 23 | + Headers 24 | 25 | Location: /messages/1337 26 | 27 | ## Create a new task [POST /tasks] 28 | 29 | Now create a task that you need to do at a later date. 30 | 31 | + Request (application/json) 32 | 33 | { 34 | "name": "Exercise in gym", 35 | "done": false, 36 | "type": "task" 37 | } 38 | 39 | + Response 201 40 | 41 | + Headers 42 | 43 | Location: /tasks/1992 44 | -------------------------------------------------------------------------------- /examples/14. JSON Schema.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # JSON Schema 4 | Every request and response can have a schema. Below you will find examples 5 | using [JSON Schema](http://json-schema.org/) to describe the format of request 6 | and response body content. 7 | 8 | ## API Blueprint 9 | + [Previous: Named Endpoints](13.%20Named%20Endpoints.md) 10 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/14.%20JSON%20Schema.md) 11 | + [Next: Advanced JSON Schema](15.%20Advanced%20JSON%20Schema.md) 12 | 13 | # Notes [/notes/{id}] 14 | 15 | + Parameters 16 | 17 | + id: abc123 (required) - Unique identifier for a note 18 | 19 | ## Get a note [GET] 20 | Gets a single note by its unique identifier. 21 | 22 | + Response 200 (application/json) 23 | 24 | + Body 25 | 26 | { 27 | "id": "abc123", 28 | "title": "This is a note", 29 | "content": "This is the note content." 30 | "tags": [ 31 | "todo", 32 | "home" 33 | ] 34 | } 35 | 36 | + Schema 37 | 38 | { 39 | "type": "object", 40 | "properties": { 41 | "id": { 42 | "type": "string" 43 | }, 44 | "title": { 45 | "type": "string" 46 | }, 47 | "content": { 48 | "type": "string" 49 | }, 50 | "tags": { 51 | "type": "array", 52 | "items": { 53 | "type": "string" 54 | } 55 | } 56 | } 57 | } 58 | 59 | ## Update a note [PATCH] 60 | Modify a note's data using its unique identifier. You can edit the `title`, 61 | `content`, and `tags`. 62 | 63 | + Request (application/json) 64 | 65 | + Body 66 | 67 | { 68 | "title": "This is another note", 69 | "tags": [ 70 | "todo", 71 | "work" 72 | ] 73 | } 74 | 75 | + Schema 76 | 77 | { 78 | "type": "object", 79 | "properties": { 80 | "title": { 81 | "type": "string" 82 | }, 83 | "content": { 84 | "type": "string" 85 | }, 86 | "tags": { 87 | "type": "array", 88 | "items": { 89 | "type": "string" 90 | } 91 | } 92 | }, 93 | "additionalProperties": false 94 | } 95 | 96 | + Response 204 97 | -------------------------------------------------------------------------------- /examples/15. Advanced JSON Schema.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | 3 | # Advanced JSON Schema 4 | The JSON body and JSON Schema for a request or response can be generated from 5 | the attributes section MSON data structure. The generated schema can also be 6 | overridden by providing an explicit schema, as you can see in the examples 7 | below. 8 | 9 | ## API Blueprint 10 | + [Previous: JSON Schema](14.%20JSON%20Schema.md) 11 | + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/15.%20Advanced%20JSON%20Schema.md) 12 | 13 | # Notes [/notes/{id}] 14 | 15 | + Parameters 16 | 17 | + id: abc123 (required) - Unique identifier for a note 18 | 19 | ## Get a note [GET] 20 | Gets a single note by its unique identifier. 21 | 22 | + Response 200 (application/json) 23 | 24 | + Attributes 25 | 26 | + id: abc123 27 | + title: This is a note 28 | + content: This is the note content. 29 | + tags: todo, home (array[string]) 30 | 31 | ## Update a note [PATCH] 32 | Modify a note's data using its unique identifier. You can edit the `title`, 33 | `content`, and `tags`. 34 | 35 | + Request (application/json) 36 | 37 | + Attributes 38 | 39 | + title: This is another note 40 | + content 41 | + tags: todo, work (array[string]) 42 | 43 | + Schema 44 | 45 | { 46 | "type": "object", 47 | "description": "This is a custom schema!", 48 | "properties": { 49 | "title": { 50 | "type": "string" 51 | }, 52 | "content": { 53 | "type": "string" 54 | }, 55 | "tags": { 56 | "type": "array", 57 | "items": { 58 | "type": "string" 59 | } 60 | } 61 | }, 62 | "additionalProperties": false 63 | } 64 | 65 | + Response 204 66 | -------------------------------------------------------------------------------- /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 (string, optional) - 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 requires 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 requires an `access_token` with `gist_write` scope. 196 | 197 | + Response 204 198 | 199 | ### Unstar a Gist [DELETE] 200 | This action requires 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 | -------------------------------------------------------------------------------- /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 (string, optional) - 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/Polls API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | HOST: http://polls.apiblueprint.org/ 3 | 4 | # Polls 5 | 6 | Polls is a simple API allowing consumers to view polls and vote in them. You can view this documentation over at [Apiary](http://docs.pollsapi.apiary.io). 7 | 8 | # Polls API Root [/] 9 | 10 | This resource does not have any attributes. Instead it offers the initial API affordances in the form of the links in the JSON body. 11 | 12 | It is recommended to follow the “url” link values, [Link](https://tools.ietf.org/html/rfc5988) or Location headers where applicable to retrieve resources. Instead of constructing your own URLs, to keep your client decoupled from implementation details. 13 | 14 | ## Retrieve the Entry Point [GET] 15 | 16 | + Response 200 (application/json) 17 | 18 | { 19 | "questions_url": "/questions" 20 | } 21 | 22 | ## Group Question 23 | 24 | Resources related to questions in the API. 25 | 26 | ## Question [/questions/{question_id}] 27 | 28 | A Question object has the following attributes: 29 | 30 | + question 31 | + published_at - An ISO8601 date when the question was published. 32 | + url 33 | + choices - An array of Choice objects. 34 | 35 | + Parameters 36 | + question_id: 1 (required, number) - ID of the Question in form of an integer 37 | 38 | ### View a Questions Detail [GET] 39 | 40 | + Response 200 (application/json) 41 | 42 | { 43 | "question": "Favourite programming language?", 44 | "published_at": "2014-11-11T08:40:51.620Z", 45 | "url": "/questions/1", 46 | "choices": [ 47 | { 48 | "choice": "Swift", 49 | "url": "/questions/1/choices/1", 50 | "votes": 2048 51 | }, { 52 | "choice": "Python", 53 | "url": "/questions/1/choices/2", 54 | "votes": 1024 55 | }, { 56 | "choice": "Objective-C", 57 | "url": "/questions/1/choices/3", 58 | "votes": 512 59 | }, { 60 | "choice": "Ruby", 61 | "url": "/questions/1/choices/4", 62 | "votes": 256 63 | } 64 | ] 65 | } 66 | 67 | ## Choice [/questions/{question_id}/choices/{choice_id}] 68 | 69 | + Parameters 70 | + question_id: 1 (required, number) - ID of the Question in form of an integer 71 | + choice_id: 1 (required, number) - ID of the Choice in form of an integer 72 | 73 | ### Vote on a Choice [POST] 74 | 75 | This action allows you to vote on a question's choice. 76 | 77 | + Response 201 78 | 79 | + Headers 80 | 81 | Location: /questions/1 82 | 83 | ## Questions Collection [/questions{?page}] 84 | 85 | + Parameters 86 | + page: 1 (optional, number) - The page of questions to return 87 | 88 | ### List All Questions [GET] 89 | 90 | + Response 200 (application/json) 91 | 92 | + Headers 93 | 94 | Link: ; rel="next" 95 | 96 | + Body 97 | 98 | [ 99 | { 100 | "question": "Favourite programming language?", 101 | "published_at": "2014-11-11T08:40:51.620Z", 102 | "url": "/questions/1", 103 | "choices": [ 104 | { 105 | "choice": "Swift", 106 | "url": "/questions/1/choices/1", 107 | "votes": 2048 108 | }, { 109 | "choice": "Python", 110 | "url": "/questions/1/choices/2", 111 | "votes": 1024 112 | }, { 113 | "choice": "Objective-C", 114 | "url": "/questions/1/choices/3", 115 | "votes": 512 116 | }, { 117 | "choice": "Ruby", 118 | "url": "/questions/1/choices/4", 119 | "votes": 256 120 | } 121 | ] 122 | } 123 | ] 124 | 125 | ### Create a New Question [POST] 126 | 127 | You may create your own question using this action. It takes a JSON object containing a question and a collection of answers in the form of choices. 128 | 129 | + question (string) - The question 130 | + choices (array[string]) - A collection of choices. 131 | 132 | + Request (application/json) 133 | 134 | { 135 | "question": "Favourite programming language?", 136 | "choices": [ 137 | "Swift", 138 | "Python", 139 | "Objective-C", 140 | "Ruby" 141 | ] 142 | } 143 | 144 | + Response 201 (application/json) 145 | 146 | + Headers 147 | 148 | Location: /questions/2 149 | 150 | + Body 151 | 152 | { 153 | "question": "Favourite programming language?", 154 | "published_at": "2014-11-11T08:40:51.620Z", 155 | "url": "/questions/2", 156 | "choices": [ 157 | { 158 | "choice": "Swift", 159 | "url": "/questions/2/choices/1", 160 | "votes": 0 161 | }, { 162 | "choice": "Python", 163 | "url": "/questions/2/choices/2", 164 | "votes": 0 165 | }, { 166 | "choice": "Objective-C", 167 | "url": "/questions/2/choices/3", 168 | "votes": 0 169 | }, { 170 | "choice": "Ruby", 171 | "url": "/questions/2/choices/4", 172 | "votes": 0 173 | } 174 | ] 175 | } 176 | 177 | -------------------------------------------------------------------------------- /examples/Polls Hypermedia API.md: -------------------------------------------------------------------------------- 1 | FORMAT: 1A 2 | HOST: http://polls.apiblueprint.org/ 3 | 4 | # Polls 5 | 6 | Polls is a simple API allowing consumers to view polls and vote in them. You can view this documentation over at [Apiary](http://docs.pollshypermedia.apiary.io/). 7 | 8 | # Polls API Root [/] 9 | 10 | This resource does not have any attributes. Instead it offers the initial API affordances. 11 | 12 | ## Retrieve the Entry Point [GET] 13 | 14 | + Response 200 (application/vnd.siren+json) 15 | 16 | { 17 | "links": [ 18 | { 19 | "rel": [ "questions" ], 20 | "href": "/questions" 21 | } 22 | ] 23 | } 24 | 25 | + Response 200 (application/hal+json) 26 | 27 | { 28 | "_links": { 29 | "questions": { "href": "/questions" } 30 | } 31 | } 32 | 33 | ## Questions Collection [/questions{?page}] 34 | 35 | + Parameters 36 | + page: 1 (optional, number) - The page of questions to return 37 | 38 | ### List All Questions [GET] 39 | 40 | + Relation: questions 41 | 42 | + Response 200 (application/vnd.siren+json) 43 | 44 | { 45 | "actions": [ 46 | { 47 | "name": "add", 48 | "href": "/questions", 49 | "method": "POST", 50 | "type": "application/json", 51 | "fields": [ 52 | { 53 | "name": "question" 54 | }, { 55 | "name": "choices" 56 | } 57 | ] 58 | } 59 | ], 60 | "links": [ 61 | { 62 | "rel": [ "next" ], 63 | "href": "/questions?page=2" 64 | }, 65 | { 66 | "rel": [ "self" ], 67 | "href": "/questions" 68 | } 69 | ], 70 | "entities": [ 71 | { 72 | "actions": [ 73 | { 74 | "name": "delete", 75 | "href": "/questions/1", 76 | "method": "DELETE" 77 | } 78 | ], 79 | "rel": [ "question" ], 80 | "properties": { 81 | "published_at": "2014-11-11T08:40:51.620Z", 82 | "question": "Favourite programming language?" 83 | }, 84 | "links": [ 85 | { 86 | "rel": [ "self" ], 87 | "href": "/questions/1" 88 | } 89 | ], 90 | "entities": [ 91 | { 92 | "actions": [ 93 | { 94 | "name": "vote", 95 | "href": "/questions/1/choices/1", 96 | "method": "POST" 97 | } 98 | ], 99 | "rel": [ "choice" ], 100 | "properties": { 101 | "choice": "Swift", 102 | "votes": 2048 103 | }, 104 | "links": [ 105 | { 106 | "rel": [ "self" ], 107 | "href": "/questions/1/choices/1" 108 | } 109 | ] 110 | }, { 111 | "actions": [ 112 | { 113 | "name": "vote", 114 | "href": "/questions/1/choices/2", 115 | "method": "POST" 116 | } 117 | ], 118 | "rel": [ "choice" ], 119 | "properties": { 120 | "choice": "Python", 121 | "votes": 1024 122 | }, 123 | "links": [ 124 | { 125 | "rel": [ "self" ], 126 | "href": "/questions/1/choices/2" 127 | } 128 | ] 129 | }, { 130 | "actions": [ 131 | { 132 | "name": "vote", 133 | "href": "/questions/1/choices/3", 134 | "method": "POST" 135 | } 136 | ], 137 | "rel": [ "choice" ], 138 | "properties": { 139 | "choice": "Objective-C", 140 | "votes": 512 141 | }, 142 | "links": [ 143 | { 144 | "rel": [ "self" ], 145 | "href": "/questions/1/choices/3" 146 | } 147 | ] 148 | }, { 149 | "actions": [ 150 | { 151 | "name": "vote", 152 | "href": "/questions/1/choices/4", 153 | "method": "POST" 154 | } 155 | ], 156 | "rel": [ "choice" ], 157 | "properties": { 158 | "choice": "Ruby", 159 | "votes": 256 160 | }, 161 | "links": [ 162 | { 163 | "rel": [ "self" ], 164 | "href": "/questions/1/choices/4" 165 | } 166 | ] 167 | } 168 | ] 169 | } 170 | ] 171 | } 172 | 173 | + Response 200 (application/hal+json) 174 | 175 | { 176 | "_links": { 177 | "self": { "href": "/questions" }, 178 | "next": { "href": "/questions?page=2" } 179 | }, 180 | "_embedded": { 181 | "question": [ 182 | { 183 | "_links": { 184 | "self": { "self": "/questions/1" } 185 | }, 186 | "_embedded": { 187 | "choice": [ 188 | { 189 | "_links": { 190 | "self": { "self": "/questions/1/choices/1" } 191 | }, 192 | "choice": "Swift", 193 | "votes": 2048 194 | }, { 195 | "_links": { 196 | "self": { "self": "/questions/1/choices/2" } 197 | }, 198 | "choice": "Python", 199 | "votes": 1024 200 | }, { 201 | "_links": { 202 | "self": { "self": "/questions/1/choices/3" } 203 | }, 204 | "choice": "Objective-C", 205 | "votes": 512 206 | }, { 207 | "_links": { 208 | "self": { "self": "/questions/1/choices/4" } 209 | }, 210 | "choice": "Ruby", 211 | "votes": 256 212 | } 213 | ] 214 | }, 215 | "question": "Favourite programming language?", 216 | "published_at": "2014-11-11T08:40:51.620Z" 217 | } 218 | ] 219 | } 220 | } 221 | 222 | ### Create a New Question [POST] 223 | 224 | You may create your own question using this action. It takes a JSON object containing a question and a collection of answers in the form of choices. 225 | 226 | + question (string) - The question 227 | + choices (array[string]) - A collection of choices. 228 | 229 | + Relation: create 230 | 231 | + Request (application/json) 232 | 233 | { 234 | "question": "Favourite programming language?", 235 | "choices": [ 236 | "Swift", 237 | "Python", 238 | "Objective-C", 239 | "Ruby" 240 | ] 241 | } 242 | 243 | + Response 201 (application/vnd.siren+json) 244 | 245 | { 246 | "actions": [ 247 | { 248 | "name": "delete", 249 | "href": "/questions/1", 250 | "method": "DELETE" 251 | } 252 | ], 253 | "properties": { 254 | "published_at": "2014-11-11T08:40:51.620Z", 255 | "question": "Favourite programming language?" 256 | }, 257 | "links": [ 258 | { 259 | "rel": [ "self" ], 260 | "href": "/questions/1" 261 | } 262 | ], 263 | "entities": [ 264 | { 265 | "actions": [ 266 | { 267 | "name": "vote", 268 | "href": "/questions/1/choices/1", 269 | "method": "POST" 270 | } 271 | ], 272 | "rel": [ "choices" ], 273 | "properties": { 274 | "choice": "Swift", 275 | "votes": 2048 276 | }, 277 | "links": [ 278 | { 279 | "rel": [ "self" ], 280 | "href": "/questions/1/choices/1" 281 | } 282 | ] 283 | }, { 284 | "actions": [ 285 | { 286 | "name": "vote", 287 | "href": "/questions/1/choices/2", 288 | "method": "POST" 289 | } 290 | ], 291 | "rel": [ "choices" ], 292 | "properties": { 293 | "choice": "Python", 294 | "votes": 1024 295 | }, 296 | "links": [ 297 | { 298 | "rel": [ "self" ], 299 | "href": "/questions/1/choices/2" 300 | } 301 | ] 302 | }, { 303 | "actions": [ 304 | { 305 | "name": "vote", 306 | "href": "/questions/1/choices/3", 307 | "method": "POST" 308 | } 309 | ], 310 | "rel": [ "choices" ], 311 | "properties": { 312 | "choice": "Objective-C", 313 | "votes": 512 314 | }, 315 | "links": [ 316 | { 317 | "rel": [ "self" ], 318 | "href": "/questions/1/choices/3" 319 | } 320 | ] 321 | }, { 322 | "actions": [ 323 | { 324 | "name": "vote", 325 | "href": "/questions/1/choices/4", 326 | "method": "POST" 327 | } 328 | ], 329 | "rel": [ "choices" ], 330 | "properties": { 331 | "choice": "Ruby", 332 | "votes": 256 333 | }, 334 | "links": [ 335 | { 336 | "rel": [ "self" ], 337 | "href": "/questions/1/choices/4" 338 | } 339 | ] 340 | } 341 | ] 342 | } 343 | 344 | + Response 201 (application/hal+json) 345 | 346 | { 347 | "_links": { 348 | "self": { "href": "/questions/1" } 349 | }, 350 | "_embedded": { 351 | "choices": [ 352 | { 353 | "_links": { 354 | "self": { "self": "/questions/1/choices/1" } 355 | }, 356 | "choice": "Swift", 357 | "votes": 2048 358 | }, { 359 | "_links": { 360 | "self": { "self": "/questions/1/choices/2" } 361 | }, 362 | "choice": "Python", 363 | "votes": 1024 364 | }, { 365 | "_links": { 366 | "self": { "self": "/questions/1/choices/3" } 367 | }, 368 | "choice": "Objective-C", 369 | "votes": 512 370 | }, { 371 | "_links": { 372 | "self": { "self": "/questions/1/choices/4" } 373 | }, 374 | "choice": "Ruby", 375 | "votes": 256 376 | } 377 | ] 378 | }, 379 | "published_at": "2014-11-11T08:40:51.620Z", 380 | "question": "Favourite programming language?" 381 | } 382 | 383 | ## Group Question 384 | 385 | Resources related to questions in the API. 386 | 387 | ## Question [/questions/{question_id}] 388 | 389 | A Question object has the following attributes: 390 | 391 | + question 392 | + published_at - An ISO8601 date when the question was published. 393 | + url 394 | + choices - An array of Choice objects. 395 | 396 | + Parameters 397 | + question_id: 1 (required, number) - ID of the Question in form of an integer 398 | 399 | ### View a Questions Detail [GET] 400 | 401 | + Relation: question 402 | 403 | + Response 200 (application/vnd.siren+json) 404 | 405 | { 406 | "actions": [ 407 | { 408 | "name": "delete", 409 | "href": "/questions/1", 410 | "method": "DELETE" 411 | } 412 | ], 413 | "properties": { 414 | "published_at": "2014-11-11T08:40:51.620Z", 415 | "question": "Favourite programming language?" 416 | }, 417 | "links": [ 418 | { 419 | "rel": [ "self" ], 420 | "href": "/questions/1" 421 | } 422 | ], 423 | "entities": [ 424 | { 425 | "actions": [ 426 | { 427 | "name": "vote", 428 | "href": "/questions/1/choices/1", 429 | "method": "POST" 430 | } 431 | ], 432 | "rel": [ "choices" ], 433 | "properties": { 434 | "choice": "Swift", 435 | "votes": 2048 436 | }, 437 | "links": [ 438 | { 439 | "rel": [ "self" ], 440 | "href": "/questions/1/choices/1" 441 | } 442 | ] 443 | }, { 444 | "actions": [ 445 | { 446 | "name": "vote", 447 | "href": "/questions/1/choices/2", 448 | "method": "POST" 449 | } 450 | ], 451 | "rel": [ "choices" ], 452 | "properties": { 453 | "choice": "Python", 454 | "votes": 1024 455 | }, 456 | "links": [ 457 | { 458 | "rel": [ "self" ], 459 | "href": "/questions/1/choices/2" 460 | } 461 | ] 462 | }, { 463 | "actions": [ 464 | { 465 | "name": "vote", 466 | "href": "/questions/1/choices/3", 467 | "method": "POST" 468 | } 469 | ], 470 | "rel": [ "choices" ], 471 | "properties": { 472 | "choice": "Objective-C", 473 | "votes": 512 474 | }, 475 | "links": [ 476 | { 477 | "rel": [ "self" ], 478 | "href": "/questions/1/choices/3" 479 | } 480 | ] 481 | }, { 482 | "actions": [ 483 | { 484 | "name": "vote", 485 | "href": "/questions/1/choices/4", 486 | "method": "POST" 487 | } 488 | ], 489 | "rel": [ "choices" ], 490 | "properties": { 491 | "choice": "Ruby", 492 | "votes": 256 493 | }, 494 | "links": [ 495 | { 496 | "rel": [ "self" ], 497 | "href": "/questions/1/choices/4" 498 | } 499 | ] 500 | } 501 | ] 502 | } 503 | 504 | + Response 200 (application/hal+json) 505 | 506 | { 507 | "_links": { 508 | "self": { "href": "/questions/1" } 509 | }, 510 | "_embedded": { 511 | "choices": [ 512 | { 513 | "_links": { 514 | "self": { "self": "/questions/1/choices/1" } 515 | }, 516 | "choice": "Swift", 517 | "votes": 2048 518 | }, { 519 | "_links": { 520 | "self": { "self": "/questions/1/choices/2" } 521 | }, 522 | "choice": "Python", 523 | "votes": 1024 524 | }, { 525 | "_links": { 526 | "self": { "self": "/questions/1/choices/3" } 527 | }, 528 | "choice": "Objective-C", 529 | "votes": 512 530 | }, { 531 | "_links": { 532 | "self": { "self": "/questions/1/choices/4" } 533 | }, 534 | "choice": "Ruby", 535 | "votes": 256 536 | } 537 | ] 538 | }, 539 | "published_at": "2014-11-11T08:40:51.620Z", 540 | "question": "Favourite programming language?" 541 | } 542 | 543 | ## Choice [/questions/{question_id}/choices/{choice_id}] 544 | 545 | + Parameters 546 | + question_id: 1 (required, number) - ID of the Question in form of an integer 547 | + choice_id: 1 (required, number) - ID of the Choice in form of an integer 548 | 549 | ### View a Choice Detail [GET] 550 | 551 | + Relation: choice 552 | 553 | + Response 200 (application/vnd.siren+json) 554 | 555 | { 556 | "actions": [ 557 | { 558 | "name": "vote", 559 | "href": "/questions/1/choices/1", 560 | "method": "POST" 561 | } 562 | ], 563 | "rel": [ "choice" ], 564 | "properties": { 565 | "choice": "Swift", 566 | "votes": 2048 567 | }, 568 | "links": [ 569 | { 570 | "rel": [ "self" ], 571 | "href": "/questions/1/choices/1" 572 | } 573 | ] 574 | } 575 | 576 | + Response 200 (application/hal+json) 577 | 578 | { 579 | "_links": { 580 | "self": { "href": "/questions/1/choices/1" } 581 | }, 582 | "choice": "Swift", 583 | "votes": 2048 584 | } 585 | 586 | ### Vote on a Choice [POST] 587 | 588 | This action allows you to vote on a question's choice. 589 | 590 | + Relation: vote 591 | 592 | + Response 201 (application/vnd.siren+json) 593 | 594 | { 595 | "actions": [ 596 | { 597 | "name": "vote", 598 | "href": "/questions/1/choices/1", 599 | "method": "POST" 600 | } 601 | ], 602 | "rel": [ "choice" ], 603 | "properties": { 604 | "choice": "Swift", 605 | "votes": 2049 606 | }, 607 | "links": [ 608 | { 609 | "rel": [ "self" ], 610 | "href": "/questions/1/choices/1" 611 | } 612 | ] 613 | } 614 | 615 | + Response 201 (application/hal+json) 616 | 617 | { 618 | "_links": { 619 | "self": "/questions/1/choices/1" 620 | }, 621 | "choice": "Swift", 622 | "votes": 2049 623 | } 624 | -------------------------------------------------------------------------------- /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/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 6 | [App.net API](http://developers.app.net). 7 | 8 | NOTE: This document is a **work in progress**. 9 | 10 | # Group Posts 11 | This section groups App.net post resources. 12 | 13 | ## Post [/stream/0/posts/{post_id}] 14 | A Post is the other central object utilized by the App.net Stream API. It has 15 | rich text and annotations which comprise all of the content a users sees in 16 | their feed. Posts are closely tied to the follow graph... 17 | 18 | + Parameters 19 | + post_id: `1` (string) - The id of the Post. 20 | 21 | + Model (application/json) 22 | 23 | ```js 24 | { 25 | "data": { 26 | "id": "1", // note this is a string 27 | "user": { 28 | ... 29 | }, 30 | "created_at": "2012-07-16T17:25:47Z", 31 | "text": "@berg FIRST post on this new site #newsocialnetwork", 32 | "html": "@berg FIRST post on this new site #newsocialnetwork.", 33 | "source": { 34 | "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4", 35 | "name": "Clientastic for iOS", 36 | "link": "http://app.net" 37 | }, 38 | "machine_only": false, 39 | "reply_to": null, 40 | "thread_id": "1", 41 | "num_replies": 3, 42 | "num_reposts": 0, 43 | "num_stars": 0, 44 | "entities": { 45 | "mentions": [{ 46 | "name": "berg", 47 | "id": "2", 48 | "pos": 0, 49 | "len": 5 50 | }], 51 | "hashtags": [{ 52 | "name": "newsocialnetwork", 53 | "pos": 34, 54 | "len": 17 55 | }], 56 | "links": [{ 57 | "text": "this new site", 58 | "url": "https://join.app.net" 59 | "pos": 20, 60 | "len": 13 61 | }] 62 | }, 63 | "you_reposted": false, 64 | "you_starred": false 65 | }, 66 | "meta": { 67 | "code": 200, 68 | } 69 | } 70 | ``` 71 | 72 | ### Retrieve a Post [GET] 73 | Returns a specific Post. 74 | 75 | + Response 200 76 | 77 | [Post][] 78 | 79 | ### Delete a Post [DELETE] 80 | Delete a Post. The current user must be the same user who created the Post. It 81 | returns the deleted Post on success. 82 | 83 | + Response 204 84 | 85 | ## Posts Collection [/stream/0/posts] 86 | A Collection of posts. 87 | 88 | + Model (application/json) 89 | 90 | ```js 91 | { 92 | "data": [ 93 | { 94 | "id": "1", // note this is a string 95 | ... 96 | }, 97 | { 98 | "id": "2", 99 | ... 100 | }, 101 | { 102 | "id": "3", 103 | ... 104 | }, 105 | ], 106 | "meta": { 107 | "code": 200, 108 | } 109 | } 110 | ``` 111 | 112 | ### Create a Post [POST] 113 | Create a new Post object. Mentions and hashtags will be parsed out of the post 114 | text, as will bare URLs... 115 | 116 | + Request 117 | 118 | [Post][] 119 | 120 | + Response 201 121 | 122 | [Post][] 123 | 124 | ### Retrieve all Posts [GET] 125 | Retrieves all posts. 126 | 127 | + Response 200 128 | 129 | [Posts Collection][] 130 | 131 | ## Stars [/stream/0/posts/{post_id}/star] 132 | A User’s stars are visible to others, but they are not automatically added to 133 | your followers’ streams. 134 | 135 | + Parameters 136 | + post_id: `1` (string) - The id of the Post. 137 | 138 | ### Star a Post [POST] 139 | Save a given Post to the current User’s stars. This is just a “save” action, 140 | not a sharing action. 141 | 142 | *Note: A repost cannot be starred. Please star the parent Post.* 143 | 144 | + Response 200 145 | 146 | [Post][] 147 | 148 | ### Unstar a Post [DELETE] 149 | Remove a Star from a Post. 150 | 151 | + Response 200 152 | 153 | [Post][] 154 | --------------------------------------------------------------------------------