Created
December 18, 2014 21:56
-
-
Save jrep/8e08281b5c52bbdad277 to your computer and use it in GitHub Desktop.
Advanced Example doesn't compile
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
FORMAT: 1A | |
# Advanced Attributes API | |
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 | |
These attributes are then reused in the `Retrieve a Coupon` action. Since they describe the complete message, no explicit JSON body example is needed. | |
Moving forward, the `Coupon` resource data structure is then reused when defining the attributes of the coupons collection resource – `Coupons`. | |
The `Create a Coupon` action also demonstrate the description of request attributes – once defined, these attributes are implied on every `Create a Coupon` request unless the request specifies otherwise. Apparently, the description of action attributes is somewhat duplicate to the definition of `Coupon` resource attributes. We will address this in the next [Data Structures](10.%20Data%20Structures.md) example. | |
## API Blueprint | |
+ [Previous: Attributes](08.%20Attributes.md) | |
+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md) | |
+ [Next: Data Structures](10.%20Data%20Structures.md) | |
# Group Coupons | |
## Coupon [/coupons/{id}] | |
A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. | |
+ Parameters | |
+ id (string) | |
The ID of the desired coupon. | |
+ Attributes (object) | |
+ id: 250FF (string) | |
+ created: 1415203908 (number) - Time stamp | |
+ percent_off: 25 (number) | |
A positive integer between 1 and 100 that represents the discount the coupon will apply. | |
+ redeem_by (number) - Date after which the coupon can no longer be redeemed | |
### Retrieve a Coupon [GET] | |
Retrieves the coupon with the given ID. | |
+ Response 200 (application/json) | |
+ Attributes (Coupon) | |
## Coupons [/coupons{?limit}] | |
+ Attributes (array[Coupon]) | |
### List all Coupons [GET] | |
Returns a list of your coupons. | |
+ Parameters | |
+ limit: 10 (optional) | |
A limit on the number of objects to be returned. Limit can range between 1 and 100 items. | |
+ Response 200 (application/json) | |
+ Attributes (Coupons) | |
### Create a Coupon [POST] | |
Creates a new Coupon. | |
+ Attributes (object) | |
+ percent_off: 25 (number) | |
+ redeem_by (number) | |
+ Request (application/json) | |
+ Response 200 (application/json) | |
+ Attributes (Coupon) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
_version: 2.1 | |
metadata: | |
- name: "FORMAT" | |
value: "1A" | |
name: "Advanced Attributes API" | |
description: "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\n\nThese attributes are then reused in the `Retrieve a Coupon` action. Since they describe the complete message, no explicit JSON body example is needed.\n\nMoving forward, the `Coupon` resource data structure is then reused when defining the attributes of the coupons collection resource – `Coupons`.\n\nThe `Create a Coupon` action also demonstrate the description of request attributes – once defined, these attributes are implied on every `Create a Coupon` request unless the request specifies otherwise. Apparently, the description of action attributes is somewhat duplicate to the definition of `Coupon` resource attributes. We will address this in the next [Data Structures](10.%20Data%20Structures.md) example.\n\n## API Blueprint\n\n+ [Previous: Attributes](08.%20Attributes.md)\n\n+ [This: Raw API Blueprint](https://raw.github.com/apiaryio/api-blueprint/master/examples/09.%20Advanced%20Attributes.md)\n\n+ [Next: Data Structures](10.%20Data%20Structures.md)\n\n" | |
resourceGroups: | |
- name: "Coupons" | |
description: | |
resources: | |
- name: "Coupon" | |
description: "A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer.\n\n" | |
uriTemplate: "/coupons/{id}" | |
model: | |
parameters: | |
- name: "id" | |
description: "The ID of the desired coupon.\n" | |
type: "string" | |
required: true | |
default: | |
example: | |
values: | |
actions: | |
- name: "Retrieve a Coupon" | |
description: "Retrieves the coupon with the given ID.\n\n" | |
method: "GET" | |
parameters: | |
examples: | |
- name: | |
description: | |
requests: | |
responses: | |
- name: "200" | |
description: | |
headers: | |
- name: "Content-Type" | |
value: "application/json" | |
body: "+ Attributes (Coupon)\n" | |
schema: | |
- name: "Coupons" | |
description: "+ Attributes (array[Coupon])\n\n" | |
uriTemplate: "/coupons{?limit}" | |
model: | |
parameters: | |
actions: | |
- name: "List all Coupons" | |
description: "Returns a list of your coupons.\n\n" | |
method: "GET" | |
parameters: | |
examples: | |
- name: | |
description: | |
requests: | |
responses: | |
- name: "200" | |
description: | |
headers: | |
- name: "Content-Type" | |
value: "application/json" | |
body: "+ Attributes (Coupons)\n" | |
schema: | |
- name: "Create a Coupon" | |
description: "Creates a new Coupon.\n\n+ Attributes (object)\n + percent_off: 25 (number)\n + redeem_by (number)\n\n" | |
method: "POST" | |
parameters: | |
examples: | |
- name: | |
description: | |
requests: | |
- name: | |
description: | |
headers: | |
- name: "Content-Type" | |
value: "application/json" | |
body: | |
schema: | |
responses: | |
- name: "200" | |
description: | |
headers: | |
- name: "Content-Type" | |
value: "application/json" | |
body: "+ Attributes (Coupon)\n" | |
schema: | |
OK. | |
warning: (5) ignoring unrecognized block :1479:307 | |
warning: (10) message-body asset is expected to be a pre-formatted code block, every of its line indented by exactly 8 spaces or 2 tabs :1893:22 | |
warning: (5) ignoring unrecognized block :2054:24;2082:94 | |
warning: (3) no parameters specified, expected a nested list of parameters, one parameter per list item :2037:140 | |
warning: (10) message-body asset is expected to be a pre-formatted code block, every of its line indented by exactly 8 spaces or 2 tabs :2215:23 | |
warning: (10) message-body asset is expected to be a pre-formatted code block, every of its line indented by exactly 8 spaces or 2 tabs :2436:22 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment