From 19d7224dcd6cfc949206b9514fbb62126a85453f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Tue, 26 May 2015 09:08:24 +0200 Subject: [PATCH 1/3] spec: allow named endpoints --- API Blueprint Specification.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/API Blueprint Specification.md b/API Blueprint Specification.md index 72f91bd..32d0ee5 100644 --- a/API Blueprint Specification.md +++ b/API Blueprint Specification.md @@ -534,7 +534,13 @@ Defined by an [HTTP request method][httpmethods] followed by [URI template][urit # -> **NOTE:** In this case the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**. +**-- or --** + +Defined by a resource [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] and an [URI template][uritemplate] enclosed in square brackets `[]`: + + # [ ] + +> **NOTE:** In the two latter cases the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**. #### Description An API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by its *URI* or a set of resources (a resource template) matching its *URI template*. From a16b1ba8d0677380eac164f598e243eb7576947f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Tue, 26 May 2015 09:18:06 +0200 Subject: [PATCH 2/3] example: named endpoints --- API Blueprint Specification.md | 2 +- examples/12. Advanced Action.md | 1 + examples/13. Named Endpoints.md | 42 +++++++++++++++++++++++++++++++++ 3 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 examples/13. Named Endpoints.md diff --git a/API Blueprint Specification.md b/API Blueprint Specification.md index 32d0ee5..466f3d9 100644 --- a/API Blueprint Specification.md +++ b/API Blueprint Specification.md @@ -540,7 +540,7 @@ Defined by a resource [name (identifier)](#def-identifier) followed by an [HTTP # [ ] -> **NOTE:** In the two latter cases the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**. +> **NOTE:** In the latter two cases the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**. #### Description An API [resource](http://www.w3.org/TR/di-gloss/#def-resource) as specified by its *URI* or a set of resources (a resource template) matching its *URI template*. diff --git a/examples/12. Advanced Action.md b/examples/12. Advanced Action.md index 2ece9d8..06b4594 100644 --- a/examples/12. Advanced Action.md +++ b/examples/12. Advanced Action.md @@ -6,6 +6,7 @@ A resource action is – in fact – a state transition. This API example demons ## API Blueprint + [Previous: Resource Model](11.%20Resource%20Model.md) + [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/12.%20Advanced%20Action.md) ++ [Next: Named Endpoints](13.%20Named%20Endpoints.md) # Tasks [/tasks/tasks{?status,priority}] diff --git a/examples/13. Named Endpoints.md b/examples/13. Named Endpoints.md new file mode 100644 index 0000000..f1086fc --- /dev/null +++ b/examples/13. Named Endpoints.md @@ -0,0 +1,42 @@ +FORMAT: 1A + +# Named Endpoints API +This API example demonstrates how to define a standalone endpoint with an identifier. + +## API Blueprint ++ [Previous: Advanced Action](12.%20Advanced%20Action.md) ++ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/13.%20Named%20Endpoints.md) + +# Group Quick start + +## Create message [POST /messages] + +Start out by creating a message for the world to see. + ++ Request (application/json) + + { "message": "Hello World!" } + ++ Response 201 + + + Headers + + Location: /messages/1337 + +## Create a new task [POST /tasks] + +Now create a task that you need to do at a later date. + ++ Request (application/json) + + { + "name": "Exercise in gym", + "done": false, + "type": "task" + } + ++ Response 201 + + + Headers + + Location: /tasks/1992 From 57cd4951fc9022ae9a4d1990498ec56cd969a334 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Mon, 8 Jun 2015 09:45:36 +0200 Subject: [PATCH 3/3] Increment API Blueprint version to 1A9 --- API Blueprint Specification.md | 4 ++-- README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/API Blueprint Specification.md b/API Blueprint Specification.md index 466f3d9..84ee333 100644 --- a/API Blueprint Specification.md +++ b/API Blueprint Specification.md @@ -1,12 +1,12 @@ --- Author: z@apiary.io -Version: 1A8 +Version: 1A9 --- # API Blueprint -#### Format 1A revision 8 +#### Format 1A revision 9 ## [I. API Blueprint Language](#def-api-blueprint-language) + [Introduction](#def-introduction) diff --git a/README.md b/README.md index 95c360f..91c5a69 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ API Blueprint, its parser, and most of its tools are completely open sourced so ## Format support -* Current format: [1A8](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A8) +* Current format: [1A9](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A9) * Format supported by Apiary: [1A8](https://github.com/apiaryio/api-blueprint/releases/tag/format-1A8) ## Getting started with API Blueprint