You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -593,13 +593,13 @@ The payload defined in this section **may** be referenced in any response or req
593
593
#### Example
594
594
595
595
# My Resource [/resource]
596
-
596
+
597
597
+ Model (text/plain)
598
598
599
599
Hello World
600
600
601
601
## Retrieve My Resource [GET]
602
-
602
+
603
603
+ Response 200
604
604
605
605
[My Resource][]
@@ -680,7 +680,7 @@ Multiple Request and Response nested sections within one transaction example **s
680
680
681
681
+ Attributes
682
682
683
-
...
683
+
...
684
684
685
685
+ Request
686
686
@@ -888,21 +888,21 @@ Defined by the `Attributes` keyword followed by an optional [MSON Type Definitio
888
888
889
889
`<Type Definition>` is the type definition of the data structure being described. If the `<Type Definition>` is not specified, an `object` base type is assumed. See [MSON Type Definition][] for details.
890
890
891
-
##### Example
891
+
##### Example
892
892
893
893
+ Attributes (object)
894
894
895
895
#### Description
896
896
This section describes a data structure using the **[Markdown Syntax for Object Notation][MSON] (MSON)**. Based on the parent section, the data structure being described is one of the following:
897
-
897
+
898
898
1. Resource data structure attributes ([Resource section](#def-resource-section))
Data structures defined in this section **may** refer to any arbitrary data structures defined in the [Data Structures section](#def-data-structures) as well as to any data structures defined by a named resource attributes description (see below).
903
903
904
904
#### Resource Attributes description
905
-
Description of the resource data structure.
905
+
Description of the resource data structure.
906
906
907
907
If defined in a named [Resource section](#def-resource-section), this data structure **may** be referenced by other data structures using the resource name.
908
908
@@ -917,9 +917,9 @@ If defined in a named [Resource section](#def-resource-section), this data struc
@@ -1032,7 +1032,7 @@ Defined by the `Data Structures` keyword.
1032
1032
# Data Structures
1033
1033
1034
1034
#### Description
1035
-
This section holds arbitrary data structures definitions defined in the form of [MSON Named Types][].
1035
+
This section holds arbitrary data structures definitions defined in the form of [MSON Named Types][].
1036
1036
1037
1037
Data structures defined in this section **may** be used in any [Attributes section][]. Similarly, any data structures defined in a [Attributes section][] of a named [Resource Section][]**may** be used in a data structure definition.
1038
1038
@@ -1053,7 +1053,7 @@ Refer to the [MSON][] specification for full details on how to define an MSON Na
Copy file name to clipboardexpand all lines: README.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -64,8 +64,8 @@ It is the task for the API Blueprint parser – [Drafter][] or one of its langua
64
64
65
65
If you are interested in building tools for API Blueprint or just to integrate it with your workflow check out the [Developing tools for API Blueprint](https://github.com/apiaryio/api-blueprint/wiki/Developing-tools-for-API-Blueprint).
66
66
67
-
## Media Type
68
-
The media type for API Blueprint is `text/vnd.apiblueprint+markdown`.
67
+
## Media Type
68
+
The media type for API Blueprint is `text/vnd.apiblueprint+markdown`.
This is one of the simplest APIs written in the **API Blueprint**.
4
+
This is one of the simplest APIs written in the **API Blueprint**.
5
5
One plain resource combined with a method and that's it! We will explain what is going on in the next installment - [Resource and Actions](02.%20Resource%20and%20Actions.md).
6
6
7
-
**Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser.
7
+
**Note:** As we progress through the examples, do not also forget to view the [Raw](https://raw.github.com/apiaryio/api-blueprint/master/examples/01.%20Simplest%20API.md) code to see what is really going on in the API Blueprint, as opposed to just seeing the output of the Github Markdown parser.
8
8
9
9
Also please keep in mind that every single example in this course is a **real API Blueprint** and as such you can **parse** it with the [API Blueprint parser](https://github.com/apiaryio/drafter) or one of its [bindings](https://github.com/apiaryio/drafter#bindings).
10
10
@@ -14,5 +14,5 @@ Also please keep in mind that every single example in this course is a **real AP
Copy file name to clipboardexpand all lines: examples/02. Resource and Actions.md
+7-7
Original file line number
Diff line number
Diff line change
@@ -4,29 +4,29 @@ FORMAT: 1A
4
4
This API example demonstrates how to define a resource with multiple actions.
5
5
6
6
## API Blueprint
7
-
+[Previous: The Simplest API](01.%20Simplest%20API.md)
7
+
+[Previous: The Simplest API](01.%20Simplest%20API.md)
8
8
+[This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/02.%20Resource%20and%20Actions.md)
9
9
+[Next: Named Resource and Actions](03.%20Named%20Resource%20and%20Actions.md)
10
10
11
11
# /message
12
12
This is our [resource](http://www.w3.org/TR/di-gloss/#def-resource). It is defined by its [URI](http://www.w3.org/TR/di-gloss/#def-uniform-resource-identifier) or, more precisely, by its [URI Template](http://tools.ietf.org/html/rfc6570).
13
13
14
-
This resource has no actions specified but we will fix that soon.
14
+
This resource has no actions specified but we will fix that soon.
15
15
16
-
## GET
16
+
## GET
17
17
Here we define an action using the `GET`[HTTP request method](http://www.w3schools.com/tags/ref_httpmethods.asp) for our resource `/message`.
18
18
19
19
As with every good action it should return a [response](http://www.w3.org/TR/di-gloss/#def-http-response). A response always bears a status code. Code 200 is great as it means all is green. Responding with some data can be a great idea as well so let's add a plain text message to our response.
20
20
21
21
+ Response 200 (text/plain)
22
22
23
23
Hello World!
24
-
25
-
## PUT
24
+
25
+
## PUT
26
26
OK, let's add another action. This time to put new data to our resource (essentially an update action). We will need to send something in a [request](http://www.w3.org/TR/di-gloss/#def-http-request) and then send a response back confirming the posting was a success (HTTP Status Code 204 ~ Resource updated successfully, no content is returned).
Copy file name to clipboardexpand all lines: examples/05. Responses.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ Group of all messages-related resources.
14
14
## My Message [/message]
15
15
16
16
### Retrieve a Message [GET]
17
-
This action has **two** responses defined: One returing a plain text and the other a JSON representation of our resource. Both has the same HTTP status code. Also both responses bear additional information in the form of a custom HTTP header. Note that both responses have set the `Content-Type` HTTP header just by specifying `(text/plain)` or `(application/json)` in their respective signatures.
17
+
This action has **two** responses defined: One returing a plain text and the other a JSON representation of our resource. Both has the same HTTP status code. Also both responses bear additional information in the form of a custom HTTP header. Note that both responses have set the `Content-Type` HTTP header just by specifying `(text/plain)` or `(application/json)` in their respective signatures.
18
18
19
19
+ Response 200 (text/plain)
20
20
@@ -41,5 +41,5 @@ This action has **two** responses defined: One returing a plain text and the oth
Copy file name to clipboardexpand all lines: examples/06. Requests.md
+4-4
Original file line number
Diff line number
Diff line change
@@ -14,10 +14,10 @@ Group of all messages-related resources.
14
14
## My Message [/message]
15
15
16
16
### Retrieve a Message [GET]
17
-
In API Blueprint requests can hold exactly the same kind of information and can be described by exactly the same structure as responses, only with different signature – using the `Request` keyword. The string that follows after the `Request` keyword is a request identifier. Again, using an explanatory and simple naming is the best way to go.
17
+
In API Blueprint requests can hold exactly the same kind of information and can be described by exactly the same structure as responses, only with different signature – using the `Request` keyword. The string that follows after the `Request` keyword is a request identifier. Again, using an explanatory and simple naming is the best way to go.
18
18
19
19
+ Request Plain Text Message
20
-
20
+
21
21
+ Headers
22
22
23
23
Accept: text/plain
@@ -33,7 +33,7 @@ In API Blueprint requests can hold exactly the same kind of information and can
33
33
Hello World!
34
34
35
35
+ Request JSON Message
36
-
36
+
37
37
+ Headers
38
38
39
39
Accept: application/json
@@ -46,7 +46,7 @@ In API Blueprint requests can hold exactly the same kind of information and can
Copy file name to clipboardexpand all lines: examples/07. Parameters.md
+10-10
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,9 @@
1
1
FORMAT: 1A
2
2
3
3
# Parameters API
4
-
In this installment of the API Blueprint course we will discuss how to describe URI parameters.
4
+
In this installment of the API Blueprint course we will discuss how to describe URI parameters.
5
5
6
-
But first let's add more messages to our system. For that we would need introduce an message identifier – id. This id will be our parameter when communicating with our API about messages.
6
+
But first let's add more messages to our system. For that we would need introduce an message identifier – id. This id will be our parameter when communicating with our API about messages.
7
7
8
8
## API Blueprint
9
9
+[Previous: Requests](06.%20Requests.md)
@@ -14,7 +14,7 @@ But first let's add more messages to our system. For that we would need introduc
14
14
Group of all messages-related resources.
15
15
16
16
## My Message [/message/{id}]
17
-
Here we have added the message `id` parameter as an [URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message resource's URI.
17
+
Here we have added the message `id` parameter as an [URI Template variable](http://tools.ietf.org/html/rfc6570) in the Message resource's URI.
18
18
Note the parameter name `id` is enclosed in curly brackets. We will discuss this parameter in the `Parameters` section below, where we will also set its example value to `1` and declare it of an arbitrary 'number' type.
19
19
20
20
+ Parameters
@@ -24,7 +24,7 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this
24
24
### Retrieve a Message [GET]
25
25
26
26
+ Request Plain Text Message
27
-
27
+
28
28
+ Headers
29
29
30
30
Accept: text/plain
@@ -40,7 +40,7 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this
40
40
Hello World!
41
41
42
42
+ Request JSON Message
43
-
43
+
44
44
+ Headers
45
45
46
46
Accept: application/json
@@ -53,10 +53,10 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this
53
53
54
54
+ Body
55
55
56
-
{
56
+
{
57
57
"id": 1,
58
-
"message": "Hello World!"
59
-
}
58
+
"message": "Hello World!"
59
+
}
60
60
61
61
### Update a Message [PUT]
62
62
@@ -74,7 +74,7 @@ Note the parameter name `id` is enclosed in curly brackets. We will discuss this
74
74
A resource representing all of my messages in the system.
75
75
76
76
We have added the query URI template parameter - `limit`. This parameter is used for limiting the number of results returned by some actions on this resource. It does not affect every possible action of this resource therefore we will discuss it only at the particular action level below.
77
-
77
+
78
78
### Retrieve all Messages [GET]
79
79
80
80
+ Parameters
@@ -83,7 +83,7 @@ We have added the query URI template parameter - `limit`. This parameter is used
Copy file name to clipboardexpand all lines: examples/09. Advanced Attributes.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
FORMAT: 1A
2
2
3
3
# Advanced Attributes API
4
-
Improving the previous [Attributes](08.%20Attributes.md) description example, this API example describes the `Coupon` resource attributes (data structure) regardless of the serialization format. These attributes can be later referenced using the resource name
4
+
Improving the previous [Attributes](08.%20Attributes.md) description example, this API example describes the `Coupon` resource attributes (data structure) regardless of the serialization format. These attributes can be later referenced using the resource name
5
5
6
6
These attributes are then reused in the `Retrieve a Coupon` action. Since they describe the complete message, no explicit JSON body example is needed.
Copy file name to clipboardexpand all lines: examples/10. Data Structures.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
FORMAT: 1A
2
2
3
3
# Data Structures API
4
-
Following [Advanced Attributes](09.%20Advanced%20Attributes.md), this example demonstrates defining arbitrary data structure to be reused by various attribute descriptions.
4
+
Following [Advanced Attributes](09.%20Advanced%20Attributes.md), this example demonstrates defining arbitrary data structure to be reused by various attribute descriptions.
5
5
6
6
Since a portion of the `Coupon` data structure is shared between the `Coupon` definition itself and the `Create a Coupon` action, it was separated into a `Coupon Base` data structure in the `Data Strucutes` API Blueprint Section. Doing so enables us to reuse it as a base-type of other attribute definitions.
0 commit comments