Advanced Attributes API


Improving the previous Attributes 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 example.

API Blueprint

Coupons
Coupon

A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer.

Retrieve a Coupon

Retrieves the coupon with the given ID.

REQUEST

Parameters
id string

The ID of the desired coupon.

RESPONSE

Headers
Content-Type application/json
200 application/json
                        {
  "id": "250FF",
  "created": 1415203908,
  "percent_off": 25,
  "redeem_by": 0
}
                      
                        {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "created": {
      "type": "number",
      "description": "Time stamp"
    },
    "percent_off": {
      "type": "number",
      "description": "A positive integer between 1 and 100 that represents the discount the coupon will apply."
    },
    "redeem_by": {
      "type": "number",
      "description": "Date after which the coupon can no longer be redeemed"
    }
  },
  "required": [
    "id"
  ]
}
                      
Coupons

List all Coupons

Returns a list of your coupons.

REQUEST

Parameters
limit number
Default
10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items.

RESPONSE

Headers
Content-Type application/json
200 application/json
                        [
  {
    "id": "250FF",
    "created": 1415203908,
    "percent_off": 25,
    "redeem_by": 0
  }
]
                      
                        {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
                      

Create a Coupon

Creates a new Coupon.

REQUEST

Headers
Content-Type application/json
application/json
                          {
  "percent_off": 25,
  "redeem_by": 0
}
                        
                          
                        

RESPONSE

Headers
Content-Type application/json
200 application/json
                        {
  "id": "250FF",
  "created": 1415203908,
  "percent_off": 25,
  "redeem_by": 0
}
                      
                        {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "created": {
      "type": "number",
      "description": "Time stamp"
    },
    "percent_off": {
      "type": "number",
      "description": "A positive integer between 1 and 100 that represents the discount the coupon will apply."
    },
    "redeem_by": {
      "type": "number",
      "description": "Date after which the coupon can no longer be redeemed"
    }
  },
  "required": [
    "id"
  ]
}