Skip to content

Instantly share code, notes, and snippets.

@jrep
Created December 18, 2014 21:56
Show Gist options
  • Save jrep/8e08281b5c52bbdad277 to your computer and use it in GitHub Desktop.
Save jrep/8e08281b5c52bbdad277 to your computer and use it in GitHub Desktop.
Advanced Example doesn't compile
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)
_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